[prev in list] [next in list] [prev in thread] [next in thread] 

List:       php-doc-cvs
Subject:    [DOC-CVS] =?utf-8?q?svn:_/phpdoc/en/trunk/language/_operators.xml?=
From:       Nikita_Popov <nikic () php ! net>
Date:       2013-09-25 11:59:47
Message-ID: svn-nikic-1380110387-331484-1576226571 () svn ! php ! net
[Download RAW message or body]

nikic                                    Wed, 25 Sep 2013 11:59:47 +0000

Revision: http://svn.php.net/viewvc?view=revision&revision=331484

Log:
Improve operator precedence docs regarding evaluation order

Associativity has nothing to do with evaluation order and we do not give any guarantees regarding that.

Changed paths:
    U   phpdoc/en/trunk/language/operators.xml

Modified: phpdoc/en/trunk/language/operators.xml
===================================================================
--- phpdoc/en/trunk/language/operators.xml	2013-09-25 11:38:58 UTC (rev 331483)
+++ phpdoc/en/trunk/language/operators.xml	2013-09-25 11:59:47 UTC (rev 331484)
@@ -43,15 +43,29 @@
     <literal>18</literal>.
    </para>
    <para>
-    When operators have equal precedence, their associativity decides
-    whether they are evaluated starting from the right, or starting from
-    the left - see the examples below.
+    When operators have equal precedence their associativity decides
+    how the operators are grouped. For example "-" is left-associative, so
+    <literal>1 - 2 - 3</literal> is grouped as <literal>(1 - 2) - 3</literal>
+    and evaluates to <literal>-4</literal>. "=" on the other hand is
+    right-associative, so <literal>$a = $b = $c</literal> is grouped as
+    <literal>$a = ($b = $c)</literal>.
    </para>
    <para>
+    Operators of equal precedence that are non-associative cannot be used
+    next to each other, for example <literal>1 &lt; 2 &gt; 1</literal> is
+    illegal in PHP. The expression <literal>1 &lt;= 1 == 1</literal> on the
+    other hand is legal, because the <literal>==</literal> operator has lesser
+    precedence than the <literal>&lt;=</literal> operator.
+   </para>
+   <para>
+    Use of parentheses, even when not strictly necessary, can often increase
+    readability of the code by making grouping explicit rather than relying
+    on the implicit operator precedence and associativity.
+   </para>
+   <para>
     The following table lists the operators in order of precedence, with
     the highest-precedence ones at the top. Operators on the same line
-    have equal precedence, in which case associativity decides the order
-    of evaluation.
+    have equal precedence, in which case associativity decides grouping.
     <table>
      <title>Operator Precedence</title>
      <tgroup cols="2">
@@ -211,14 +225,6 @@
     </table>
    </para>
    <para>
-    For operators of equal precedence, left associativity means that
-    evaluation proceeds from left to right, and right associativity means
-    the opposite. For operators of equal precedence that are non-associative
-    those operators may not associate with themselves. So for example, the
-    statement <literal>1 &lt; 2 &gt; 1</literal>, is illegal in PHP. Whereas,
-    the statement <literal>1 &lt;= 1 == 1</literal> is not, because the
-    <constant>T_IS_EQUAL</constant> operator has lesser precedence than the
-    <constant>T_IS_SMALLER_OR_EQUAL</constant> operator.
     <example>
      <title>Associativity</title>
      <programlisting role="php">
@@ -239,9 +245,28 @@
 ]]>
      </programlisting>
     </example>
-    Use of parentheses, even when not strictly necessary, can often increase
-    readability of the code.
    </para>
+   <para>
+    Operator precedence and associativity only determine how expressions
+    are grouped, they do not specify an order of evaluation. PHP does not
+    (in the general case) specify in which order an expression is evaluated
+    and code that assumes a specific order of evaluation should be avoided,
+    because it can change between versions of PHP without further notice.
+    <example>
+     <title>Undefined order of evaluation</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$a = 1;
+echo $a + $a++; // may print either 2 or 3
+
+$i = 1;
+$array[$i] = $i++; // may set either index 1 or 2
+?>
+]]>
+     </programlisting>
+    </example>
+   </para>
    <note>
     <para>
      Although <literal>=</literal> has a lower precedence than



-- 
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[prev in list] [next in list] [prev in thread] [next in thread]