<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.list" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>list</refname>
  <refpurpose>Assign variables as if they were an array</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>list</methodname>
   <methodparam><type>mixed</type><parameter>varname</parameter></methodparam>
   <methodparam rep="repeat" choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
  </methodsynopsis>
  <para>
   Like <function>array</function>, this is not really a function,
   but a language construct.  <function>list</function> is used to
   assign a list of variables in one operation.
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>varname</parameter></term>
     <listitem>
      <para>
       A variable.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the assigned array.
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>list</function> examples</title>
    <programlisting role="php">
<![CDATA[
<?php

$info = array('coffee', 'brown', 'caffeine');

// Listing all the variables
list($drink, $color, $power) = $info;
echo "$drink is $color and $power makes it special.\n";

// Listing some of them
list($drink, , $power) = $info;
echo "$drink has $power.\n";

// Or let's skip to only the third one
list( , , $power) = $info;
echo "I need $power!\n";

// list() doesn't work with strings
list($bar) = "abcde";
var_dump($bar); // NULL
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>An example use of <function>list</function></title>
    <programlisting role="php">
<![CDATA[
<table>
 <tr>
  <th>Employee name</th>
  <th>Salary</th>
 </tr>

<?php
$result = $pdo->query("SELECT id, name, salary FROM employees");
while (list($id, $name, $salary) = $result->fetch(PDO::FETCH_NUM)) {
    echo " <tr>\n" .
          "  <td><a href=\"info.php?id=$id\">$name</a></td>\n" .
          "  <td>$salary</td>\n" .
          " </tr>\n";
}

?>

</table>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Using nested <function>list</function></title>
    <programlisting role="php">
<![CDATA[
<?php

list($a, list($b, $c)) = array(1, array(2, 3));

var_dump($a, $b, $c);

?>
]]>
    </programlisting>
    <screen>
<![CDATA[
int(1)
int(2)
int(3)
]]>
    </screen>
   </example>
  </para>
  <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>
    <para>
     Gives the following output (note the order of the elements compared in
     which order they were written in the <function>list</function> syntax):
    </para>
    <screen>
<![CDATA[
array(3) {
  [2]=>
  string(8) "caffeine"
  [1]=>
  string(5) "brown"
  [0]=>
  string(6) "coffee"
}
]]>
    </screen>
   </example>
  </para>
 </refsect1>
 <refsect1 role="notes">
  &reftitle.notes;
  <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 right; which it isn't. It's
    assigned in the reverse order.
   </para>
  </warning>
  <warning>
   <para>
    Modification of the array during <function>list</function> execution (e.g.
    using <literal>list($a, $b) = $b</literal>) results in undefined behavior.
   </para>
  </warning>
  <note>
   <para>
    <function>list</function> only works on numerical arrays and assumes
    the numerical indices start at 0.
   </para>
  </note>
 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>each</function></member>
    <member><function>array</function></member>
    <member><function>extract</function></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>

<!-- 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:"~/.phpdoc/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
-->