each.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.each" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>each</refname>
  <refpurpose>Return the current key and value pair from an array and advance the array cursor</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
   &warn.deprecated.function-7-2-0.removed-8-0-0;
 </refsynopsisdiv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>each</methodname>
   <methodparam><type class="union"><type>array</type><type>object</type></type><parameter role="reference">array</parameter></methodparam>
  </methodsynopsis>
  <para>
   Return the current key and value pair from an array and advance the array
   cursor.
  </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>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>array</parameter></term>
     <listitem>
      <para>
       The input array.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the current key and value pair from the array
   <parameter>array</parameter>. 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>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <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>
    &example.outputs;
    <screen>
<![CDATA[
a => apple
b => banana
c => cranberry
]]>
    </screen>
   </example>
  </para>
  <caution>
   <para>
    Because assigning an array to another variable resets the original
    array's pointer, our example above would cause an endless loop had we
    assigned <varname>$fruit</varname> to another variable inside the
    loop.
   </para>
  </caution>
  <warning>
   <para>
    <function>each</function> will also accept objects, but may return unexpected 
    results. It's therefore not recommended to iterate though object properties 
    with <function>each</function>.
   </para>
  </warning>
 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>key</function></member>
    <member><function>list</function></member>
    <member><function>current</function></member>
    <member><function>reset</function></member>
    <member><function>next</function></member>
    <member><function>prev</function></member>
    <member>&foreach;</member>
    <member><link linkend="language.oop5.iterations">Object Iteration</link></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
-->