- Document list() specific behaviour of the order of assigning the values to

the variables.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@85054 c90b9560-bf6c-de11-be94-00142212c4b1

reference/array/functions/list.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
   <refentry id="function.list">
    <refnamediv>
@@ -79,6 +79,44 @@ while (list ($id, $name, $salary) = mysql_fetch_row ($result)) {
       </programlisting>
      </example>
     </para>
+    <warning>
+    <para>
+     <function>list</function> assigns the values starting with the right-most
+     parameter. If you are using plain variables, you don't have to worry
+     about this. But if you are using arrays with indices you usually expect
+     the order of the indices in the array the same you wrote in the
+     <function>list</function> from left to write; which it isn't. It's
+     assigned in the reverse order.
+    </para>
+    </warning>
+    <para>
+     <example>
+      <title>Using <function>list</function> with array indices</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+$info = array('coffee', 'brown', 'caffeine');
+
+list($a[0], $a[1], $a[2]) = $info;
+
+var_dump($a);
+]]>
+      </programlisting>
+     </example>
+     Gives the following output (note the order of the elements compared in
+     which order they were written in the <function>list</function> syntax):
+     <screen>
+array(3) {
+  [2]=>
+  string(8) "caffeine"
+  [1]=>
+  string(5) "brown"
+  [0]=>
+  string(6) "coffee"
+}
+     </screen>
+    </para>
     <para>
      See also <function>each</function>, <function>array</function> 
      and <function>extract</function>.