php-doc-en/reference/array/functions/each.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.15 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
  <refentry id="function.each">
   <refnamediv>
    <refname>each</refname>
    <refpurpose>
     Return the current key and value pair from an array and advance
     the array cursor
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>each</methodname>
      <methodparam><type>array</type><parameter>&amp;array</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the current key and value pair from the array
     <parameter>array</parameter> and advances the array cursor. This
     pair is returned in a four-element array, with the keys
     <literal>0</literal>, <literal>1</literal>,
     <literal>key</literal>, and
     <literal>value</literal>. Elements <literal>0</literal> and
     <literal>key</literal> contain the key name of the array
     element, and <literal>1</literal> and
     <literal>value</literal> contain the data.
    </para>
    <para>
     If the internal pointer for the array points past the end of the
     array contents, <function>each</function> returns
     &false;.
    </para>
    <para>
     <example>
      <title><function>each</function> examples</title>
      <programlisting role="php">
<![CDATA[
<?php
$foo = array("bob", "fred", "jussi", "jouni", "egon", "marliese");
$bar = each($foo);
print_r($bar);
?>
]]>
      </programlisting>
      <para>
       <varname>$bar</varname> now contains the following key/value
       pairs:
      </para>
      <screen>
<![CDATA[
Array
(
    [1] => bob
    [value] => bob
    [0] => 0
    [key] => 0
)
]]>
      </screen>
     </example>
    </para>
    <para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$foo = array("Robert" => "Bob", "Seppo" => "Sepi");
$bar = each($foo);
print_r($bar);
?>
]]>
      </programlisting>
      <para>
       <varname>$bar</varname> now contains the following key/value
       pairs:
      </para>
      <screen>
<![CDATA[
Array
(
    [1] => Bob
    [value] => Bob
    [0] => Robert
    [key] => Robert
)
]]>
      </screen>
     </informalexample>
    </para>
    <para>
     <function>each</function> is typically used in conjunction with
     <function>list</function> to traverse an array, here's an 
     example:
     <example>
      <title>Traversing an array with <function>each</function></title>
      <programlisting role="php">
<![CDATA[
<?php
$fruit = array('a' => 'apple', 'b' => 'banana', 'c' => 'cranberry');

reset($fruit);
while (list($key, $val) = each($fruit)) {
    echo "$key => $val\n";
}
?>
]]>
      </programlisting>
      <para>
       Outputs:
      </para>
      <screen>
<![CDATA[
a => apple
b => banana
c => cranberry
]]>
      </screen>
     </example>
    </para>
    <para>
     After <function>each</function> has executed, the array cursor
     will be left on the next element of the array, or past the last
     element if it hits the end of the array. You have to use
     <function>reset</function> if you want to traverse the array
     again using each.
    </para>
    <caution>
     <para>
      Because assigning an array to another variable resets the original
      arrays pointer, our example above would cause an endless loop had we
      assigned <varname>$fruit</varname> to another variable inside the
      loop.
     </para>
    </caution>
    <para>
     See also <function>key</function>, <function>list</function>,
     <function>current</function>, <function>reset</function>,
     <function>next</function>, <function>prev</function>, and 
     <link linkend="control-structures.foreach">foreach</link>.
    </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:"../../../../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
-->