<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.32 $ -->
 <chapter id="language.operators">
  <title>Operators</title>
  <simpara>
  </simpara>
  
  <sect1 id="language.operators.arithmetic">
   <title>Arithmetic Operators</title>
   <simpara>
    Remember basic arithmetic from school? These work just
    like those.
   </simpara>
   <table>
    <title>Arithmetic Operators</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Example</entry>
       <entry>Name</entry>
       <entry>Result</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>$a + $b</entry>
       <entry>Addition</entry>
       <entry>Sum of $a and $b.</entry>
      </row>
      <row>
       <entry>$a - $b</entry>
       <entry>Subtraction</entry>
       <entry>Difference of $a and $b.</entry>
      </row>
      <row>
       <entry>$a * $b</entry>
       <entry>Multiplication</entry>
       <entry>Product of $a and $b.</entry>
      </row>
      <row>
       <entry>$a / $b</entry>
       <entry>Division</entry>
       <entry>Quotient of $a and $b.</entry>
      </row>
      <row>
       <entry>$a % $b</entry>
       <entry>Modulus</entry>
       <entry>Remainder of $a divided by $b.</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   
   <simpara>
    The division operator ("/") returns an integer value (the result
    of an integer division) if the two operands are integers (or
    strings that get converted to integers) and the quotient is an
    integer. If either operand is a floating-point value, or the
    operation results in a non-integer value, a floating-point value
    is returned.
   </simpara>
  </sect1>
  
  <sect1 id="language.operators.assignment">
   <title>Assignment Operators</title>
   <simpara>
    The basic assignment operator is "=". Your first inclination might
    be to think of this as "equal to". Don't. It really means that the
    the left operand gets set to the value of the expression on the
    rights (that is, "gets set to").
   </simpara>
   <para>
    The value of an assignment expression is the value assigned. That
    is, the value of "$a = 3" is 3. This allows you to do some tricky
    things: 
    <informalexample>
     <programlisting role="php"> 
<![CDATA[
$a = ($b = 4) + 5; // $a is equal to 9 now, and $b has been set to 4.
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    In addition to the basic assignment operator, there are "combined
    operators" for all of the binary arithmetic and string operators
    that allow you to use a value in an expression and then set its
    value to the result of that expression. For example:
    <informalexample>
     <programlisting role="php">
<![CDATA[
$a = 3;
$a += 5; // sets $a to 8, as if we had said: $a = $a + 5;
$b = "Hello ";
$b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!";
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    Note that the assignment copies the original variable to the new
    one (assignment by value), so changes to one will not affect the
    other. This may also have relevance if you need to copy something
    like a large array inside a tight loop. PHP 4 supports assignment
    by reference, using the <computeroutput>$var =
    &amp;$othervar;</computeroutput> syntax, but this is not possible
    in PHP 3. 'Assignment by reference' means that both variables end
    up pointing at the same data, and nothing is copied anywhere. 
    To learn more about references, please read <link 
    linkend="language.references">References explained</link>.
   </para>
  </sect1>

  <sect1 id="language.operators.bitwise">
   <title>Bitwise Operators</title>
   <simpara>
    Bitwise operators allow you to turn specific bits within an
    integer on or off. If both the left- and right-hand parameters are
    strings, the bitwise operator will operate on the characters in this
    string.
   </simpara>
   <para>
    <informalexample>
     <programlisting>
<![CDATA[
<?php
    echo 12 ^ 9; // Outputs '5'

    echo "12" ^ "9"; // Outputs the Backspace character (ascii 8)
                     // ('1' (ascii 49)) ^ ('9' (ascii 57)) = #8

    echo "hallo" ^ "hello"; // Outputs the ascii values #0 #4 #0 #0 #0
                            // 'a' ^ 'e' = #4
?>
]]>
     </programlisting>
    </informalexample> 
   </para>

   <table>
    <title>Bitwise Operators</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Example</entry>
       <entry>Name</entry>
       <entry>Result</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>$a &amp; $b</entry>
       <entry>And</entry>
       <entry>Bits that are set in both $a and $b are set.</entry>
      </row>
      <row>
       <entry>$a | $b</entry>
       <entry>Or</entry>
       <entry>Bits that are set in either $a or $b are set.</entry>
      </row>
      <row>
       <entry>$a ^ $b</entry>
       <entry>Xor</entry>
       <entry>
	Bits that are set in $a or $b but not both are set.
       </entry>
      </row>
      <row>
       <entry>~ $a</entry>
       <entry>Not</entry>
       <entry>
	Bits that are set in $a are not set, and vice versa.
       </entry>
      </row>
      <row>
       <entry>$a &lt;&lt; $b</entry>
       <entry>Shift left</entry>
       <entry>
	Shift the bits of $a $b steps to the left (each step means
	"multiply by two")
       </entry>
      </row>
      <row>
       <entry>$a &gt;&gt; $b</entry>
       <entry>Shift right</entry>
       <entry>
	Shift the bits of $a $b steps to the right (each step means
	"divide by two")
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </sect1>

  <sect1 id="language.operators.comparison">
   <title>Comparison Operators</title>
   <simpara>
    Comparison operators, as their name implies, allow you to compare
    two values.
   </simpara>
   <table>
    <title>Comparison Operators</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Example</entry>
       <entry>Name</entry>
       <entry>Result</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>$a == $b</entry>
       <entry>Equal</entry>
       <entry>&true; if $a is equal to $b.</entry>
      </row>
      <row>
       <entry>$a === $b</entry>
       <entry>Identical</entry>
       <entry>
	&true; if $a is equal to $b, and they are of the same
	type. (PHP 4 only)
       </entry>
      </row>
      <row>
       <entry>$a != $b</entry>
       <entry>Not equal</entry>
       <entry>&true; if $a is not equal to $b.</entry>
      </row>
      <row>
       <entry>$a &lt;> $b</entry>
       <entry>Not equal</entry>
       <entry>&true; if $a is not equal to $b.</entry>
      </row>
      <row>
       <entry>$a !== $b</entry>
       <entry>Not identical</entry>
       <entry>
	&true; if $a is not equal to $b, or they are not of the same
	type. (PHP 4 only)
       </entry>
      </row>
      <row>
       <entry>$a &lt; $b</entry>
       <entry>Less than</entry>
       <entry>&true; if $a is strictly less than $b.</entry>
      </row>
      <row>
       <entry>$a &gt; $b</entry>
       <entry>Greater than</entry>
       <entry>&true; if $a is strictly greater than $b.</entry>
      </row>
      <row>
       <entry>$a &lt;= $b</entry>
       <entry>Less than or equal to </entry>
       <entry>&true; if $a is less than or equal to $b.</entry>
      </row>
      <row>
       <entry>$a &gt;= $b</entry>
       <entry>Greater than or equal to </entry>
       <entry>&true; if $a is greater than or equal to $b.</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   <para>
    Another conditional operator is the "?:" (or ternary) operator,
    which operates as in C and many other languages.
    <informalexample>
     <programlisting>
<![CDATA[
(expr1) ? (expr2) : (expr3);
]]>
     </programlisting>
    </informalexample> 
    This expression evaluates to <replaceable>expr2</replaceable> if
    <replaceable>expr1</replaceable> evaluates to &true;, and
    <replaceable>expr3</replaceable> if
    <replaceable>expr1</replaceable> evaluates to &false;.
   </para>
  </sect1>

  <sect1 id="language.operators.errorcontrol">
   <title>Error Control Operators</title>
   <simpara>
    PHP supports one error control operator: the at sign (@). When
    prepended to an expression in PHP, any error messages that might
    be generated by that expression will be ignored. 
   </simpara>
   <simpara>
    If the <link linkend="ini.track-errors">track_errors</link>
    feature is enabled, any error message generated by the expression
    will be saved in the global variable $php_errormsg. This variable
    will be overwritten on each error, so check early if you want to
    use it.
   </simpara>
   <para>
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
/* Intentional file error */
$my_file = @file ('non_existent_file') or
    die ("Failed opening file: error was '$php_errormsg'");

// this works for any expression, not just functions:
$value = @$cache[$key]; 
// will not issue a notice if the index $key doesn't exist.

?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <note>
    <simpara>
     The @-operator works only on expressions. A simple rule of thumb
     is: if you can take the value of something, you can prepend the @
     operator to it. For instance, you can prepend it to variables,
     function and <function>include</function> calls, constants, and
     so forth. You cannot prepend it to function or class definitions,
     or conditional structures such as <literal>if</literal> and
     <literal>foreach</literal>, and so forth.
    </simpara>
   </note>
   <simpara>
    See also <function>error_reporting</function>.
   </simpara>
   <warning>
    <para>
     Currently the "@" error-control operator prefix will even disable
     error reporting for critical errors that will terminate script
     execution. Among other things, this means that if you use "@" to
     suppress errors from a certain function and either it isn't
     available or has been mistyped, the script will die right there
     with no indication as to why.
    </para>
   </warning>
  </sect1>
  
  <sect1 id="language.operators.execution">
   <title>Execution Operators</title>
   <para>
    PHP supports one execution operator: backticks (``). Note that
    these are not single-quotes! PHP will attempt to execute the
    contents of the backticks as a shell command; the output will be
    returned (i.e., it won't simply be dumped to output; it can be
    assigned to a variable).
    <informalexample>
     <programlisting role="php">
<![CDATA[
$output = `ls -al`;
echo "<pre>$output</pre>";
]]>
     </programlisting>
    </informalexample>
   </para>
   <note>
    <para>
     The backtick operator is disabled when <link
     linkend="ini.safe-mode">safe mode</link> is enabled
     or <function>shell_exec</function> is disabled.
    </para>
   </note>
   <para>
    See also <function>escapeshellcmd</function>, <function>exec</function>,
    <function>passthru</function>, <function>popen</function>,
    <function>shell_exec</function>, and <function>system</function>.
   </para>
  </sect1>

  <sect1 id="language.operators.increment">
   <title>Incrementing/Decrementing Operators</title>
   <para>
    PHP supports C-style pre- and post-increment and decrement
    operators.
   </para>
   <table>
    <title>Increment/decrement Operators</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Example</entry>
       <entry>Name</entry>
       <entry>Effect</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>++$a</entry>
       <entry>Pre-increment</entry>
       <entry>Increments $a by one, then returns $a.</entry>
      </row>
      <row>
       <entry>$a++</entry>
       <entry>Post-increment</entry>
       <entry>Returns $a, then increments $a by one.</entry>
      </row>
      <row>
       <entry>--$a</entry>
       <entry>Pre-decrement</entry>
       <entry>Decrements $a by one, then returns $a.</entry>
      </row>
      <row>
       <entry>$a--</entry>
       <entry>Post-decrement</entry>
       <entry>Returns $a, then decrements $a by one.</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   <para>
    Here's a simple example script:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
echo "<h3&gt;Postincrement</h3&gt;";
$a = 5;
echo "Should be 5: " . $a++ . "<br>\n";
echo "Should be 6: " . $a . "<br>\n";

echo "<h3>Preincrement</h3>";
$a = 5;
echo "Should be 6: " . ++$a . "<br>\n";
echo "Should be 6: " . $a . "<br>\n";

echo "<h3>Postdecrement</h3>";
$a = 5;
echo "Should be 5: " . $a-- . "<br>\n";
echo "Should be 4: " . $a . "<br>\n";

echo "<h3>Predecrement</h3>";
$a = 5;
echo "Should be 4: " . --$a . "<br>\n";
echo "Should be 4: " . $a . "<br>\n";
?>
]]>
     </programlisting>
    </informalexample>
   </para>
  </sect1>

  <sect1 id="language.operators.logical">
   <title>Logical Operators</title>

   <table>
    <title>Logical Operators</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Example</entry>
       <entry>Name</entry>
       <entry>Result</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>$a and $b</entry>
       <entry>And</entry>
       <entry>&true; if both $a and $b are &true;.</entry>
      </row>
      <row>
       <entry>$a or $b</entry>
       <entry>Or</entry>
       <entry>&true; if either $a or $b is &true;.</entry>
      </row>
      <row>
       <entry>$a xor $b</entry>
       <entry>Xor</entry>
       <entry>&true; if either $a or $b is &true;, but not both.</entry>
      </row>
      <row>
       <entry>! $a</entry>
       <entry>Not</entry>
       <entry>&true; if $a is not &true;.</entry>
      </row>
      <row>
       <entry>$a &amp;&amp; $b</entry>
       <entry>And</entry>
       <entry>&true; if both $a and $b are &true;.</entry>
      </row>
      <row>
       <entry>$a || $b</entry>
       <entry>Or</entry>
       <entry>&true; if either $a or $b is &true;.</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   <simpara>
    The reason for the two different variations of "and" and "or"
    operators is that they operate at different precedences. (See
    <link linkend="language.operators.precedence">Operator
    Precedence</link>.)
   </simpara>
  </sect1>

  <sect1 id="language.operators.precedence">
   <title>Operator Precedence</title>
   <para>
    The precedence of an operator specifies how "tightly" it binds two
    expressions together. For example, in the expression <literal>1 +
    5 * 3</literal>, the answer is <literal>16</literal> and not
    <literal>18</literal> because the multiplication ("*") operator
    has a higher precedence than the addition ("+") operator.
    Parentheses may be used to force precedence, if necessary. For
    instance: <literal>(1 + 5) * 3</literal> evaluates to
    <literal>18</literal>.
   </para>
   <para>
    The following table lists the precedence of operators with the
    lowest-precedence operators listed first.
    <table>
     <title>Operator Precedence</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Associativity</entry>
        <entry>Operators</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>left</entry>
        <entry>,</entry>
       </row>
       <row>
        <entry>left</entry>
        <entry>or</entry>
       </row>
       <row>
        <entry>left</entry>
        <entry>xor</entry>
       </row>
       <row>
        <entry>left</entry>
        <entry>and</entry>
       </row>
       <row>
        <entry>right</entry>
        <entry>print</entry>
       </row>
       <row>
        <entry>left</entry>
        <entry>
         = += -= *= /= .= %= &amp;= |= ^= ~= &lt;&lt;= &gt;&gt;=
        </entry>
       </row>
       <row>
        <entry>left</entry>
        <entry>? :</entry>
       </row>
       <row>
        <entry>left</entry>
        <entry>||</entry>
       </row>
       <row>
        <entry>left</entry>
        <entry>&amp;&amp;</entry>
       </row>
       <row>
        <entry>left</entry>
        <entry>|</entry>
       </row>
       <row>
        <entry>left</entry>
        <entry>^</entry>
       </row>
       <row>
        <entry>left</entry>
        <entry>&amp;</entry>
       </row>
       <row>
        <entry>non-associative</entry>
        <entry>== != === !==</entry>
       </row>
       <row>
        <entry>non-associative</entry>
        <entry>&lt; &lt;= &gt; &gt;=</entry>
       </row>
       <row>
        <entry>left</entry>
        <entry>&lt;&lt; &gt;&gt;</entry>
       </row>
       <row>
        <entry>left</entry>
        <entry>+ - .</entry>
       </row>
       <row>
        <entry>left</entry>
        <entry>* / %</entry>
       </row>
       <row>
        <entry>right</entry>
        <entry>! ~ ++ -- (int) (double) (string) (array) (object) @</entry>
       </row>
       <row>
        <entry>right</entry>
        <entry>[</entry>
       </row>
       <row>
        <entry>non-associative</entry>
        <entry>new</entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
  </sect1>

  <sect1 id="language.operators.string">
   <title>String Operators</title>
   <simpara>
    There are two string operators. The first is the concatenation
    operator ('.'), which returns the concatenation of its right and
    left arguments. The second is the concatenating assignment
    operator ('.='), which appends the argument on the right side to
    the argument on the left side. Please read <link
    linkend="language.operators.assignment">Assignment
    Operators</link> for more information.
   </simpara>

   <para>
    <informalexample>
     <programlisting role="php">
<![CDATA[
$a = "Hello ";
$b = $a . "World!"; // now $b contains "Hello World!"

$a = "Hello ";
$a .= "World!";     // now $a contains "Hello World!"
]]>
     </programlisting>
    </informalexample>
   </para>
  </sect1>

 </chapter>
 
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->