From e28fdbe16cd4f7347800af2464b73a7507e3cc92 Mon Sep 17 00:00:00 2001
From: Nikita Popov <nikic@php.net>
Date: Wed, 25 Sep 2013 11:59:47 +0000
Subject: [PATCH] Improve operator precedence docs regarding evaluation order

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

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@331484 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language/operators.xml | 55 ++++++++++++++++++++++++++++++------------
 1 file changed, 40 insertions(+), 15 deletions(-)

diff --git a/language/operators.xml b/language/operators.xml
index 95d06825f9..9d3eac6d9b 100644
--- a/language/operators.xml
+++ b/language/operators.xml
@@ -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,8 +245,27 @@ echo ++$a + $a++; // may print 4 or 5
 ]]>
      </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>