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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- 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>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
     <emphasis>0</emphasis>, <emphasis>1</emphasis>,
     <emphasis>key</emphasis>, and
     <emphasis>value</emphasis>. Elements <emphasis>0</emphasis> and
     <emphasis>key</emphasis> contain the key name of the array
     element, and <emphasis>1</emphasis> and
     <emphasis>value</emphasis> 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[
$foo = array ("bob", "fred", "jussi", "jouni", "egon", "marliese");
$bar = each ($foo);
]]>
      </programlisting>
      <para>
       <varname>$bar</varname> now contains the following key/value
       pairs:
       <itemizedlist spacing="compact">
        <listitem><simpara>0 =&gt; 0</simpara></listitem>
        <listitem><simpara>1 =&gt; 'bob'</simpara></listitem>
        <listitem><simpara>key =&gt; 0</simpara></listitem>
        <listitem><simpara>value =&gt; 'bob'</simpara></listitem>
       </itemizedlist>
       <programlisting role="php">
<![CDATA[
$foo = array ("Robert" => "Bob", "Seppo" => "Sepi");
$bar = each ($foo);
]]>
       </programlisting>
      </para>
      <para>
       <varname>$bar</varname> now contains the following key/value
       pairs:
       <itemizedlist spacing="compact">
        <listitem><simpara>0 =&gt; 'Robert'</simpara></listitem>
        <listitem><simpara>1 =&gt; 'Bob'</simpara></listitem>
        <listitem><simpara>key =&gt; 'Robert'</simpara></listitem>
        <listitem><simpara>value =&gt; 'Bob'</simpara></listitem>
       </itemizedlist>
      </para>
     </example>
    </para>
    <para>
     <function>each</function> is typically used in conjunction with
     <function>list</function> to traverse an array; for instance,
     <varname>$_POST</varname>:
     <example>
      <title>
       Traversing <varname>$_POST</varname> with
       <function>each</function>
      </title>
      <programlisting role="php">
<![CDATA[
echo "Values submitted via POST method:<br />\n";
reset ($_POST);
while (list ($key, $val) = each ($_POST)) {
    echo "$key => $val<br />\n";
}
]]>
      </programlisting>
     </example>
    </para>
    <para>
     After <function>each</function> has executed, the array cursor
     will be left on the next element of the array, or on 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>
    <para>
     See also <function>key</function>, <function>list</function>,
     <function>current</function>, <function>reset</function>,
     <function>next</function>, <function>prev</function>, and 
     <function>foreach</function>.
    </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
-->