<reference id="ref.array">
  <title>Array Functions</title>
  <titleabbrev>Arrays</titleabbrev>

  <refentry id="function.array">
   <refnamediv>
    <refname>array</refname>
    <refpurpose>
     Create an array
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>array <function>array</function></funcdef>
     <varargs>
    </funcsynopsis>
    <para>
     Returns an array of the parameters.  The parameters can be given
     an index with the <literal>=&gt;</literal> operator.

    <para>
     Note that <function>array</function> really is a language
     construct used to represent literal arrays, and not a regular
     function.

    <para>
     The following example demonstrates how to create a
     two-dimensional array, how to specify keys for associative
     arrays, and how to skip-and-continue numeric indices in normal
     arrays.

     <example>
      <title><function>array</function> example</title>
      <programlisting>
$fruits = array(
    "fruits"  => array("a"=>"orange","b"=>"banana","c"=>"apple"),
    "numbers" => array(1, 2, 3, 4, 5, 6)
    "holes"   => array("first", 5 => "second", "third")
);
</programlisting></example>

    <para>
     See also:
     <function>list</function>.
   </refsect1>
  </refentry>


  <refentry id="function.array-walk">
   <refnamediv>
    <refname>array_walk</refname>
    <refpurpose>
     Apply a function to every member of an array.
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>array_walk</function></funcdef>
     <paramdef>array <parameter>arr</parameter></paramdef>
     <paramdef>string <parameter>func</parameter></paramdef>
    </funcsynopsis>

    <simpara>
     Applies the function named by <parameter>func</parameter> to each
     element of <parameter>arr</parameter>. The elements are passed as
     the first argument of <parameter>func</parameter>; if
     <parameter>func</parameter> requires more than one argument, a
     warning will be generated each time
     <function>array_walk</function> calls
     <parameter>func</parameter>. These warnings may be suppressed by
     prepending the '@' sign to the <function>array_walk</function>
     call, or by using <function>error_reporting</function>.

    <para>
     Note that <parameter>func</parameter> will actually be working
     with the elements of <parameter>arr</parameter>, so any changes
     made to those elements will actually be made in the array itself.

    <para>
     <example>
      <title><function>array_walk</function> example</title>
      <programlisting>
$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple");

function test_alter( $item1 ) {
   $item1 = 'bogus';
}

function test_print( $item2 ) {
   echo "$item2&lt;br&gt;\n";
}

array_walk( $fruits, 'test_print' );
array_walk( $fruits, 'test_alter' );
array_walk( $fruits, 'test_print' );
      </programlisting>
     </example>

    <simpara>
     See also <function>each</function> and <function>list</function>.

   </refsect1>
  </refentry>



  <refentry id="function.arsort">
   <refnamediv>
    <refname>arsort</refname>
    <refpurpose>
     Sort an array in reverse order and maintain index association
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>void <function>arsort</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
    </funcsynopsis>
    <para>
     This function sorts an array such that array indices maintain their 
     correlation with the array elements they are associated with.  This is
     used mainly when sorting associative arrays where the actual element
     order is significant.  
     <example>
      <title><function>arsort</function> example</title>
      <programlisting>
$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple");
arsort($fruits);
for(reset($fruits); $key = key($fruits); next($fruits)) {
    echo "fruits[$key] = ".$fruits[$key]."\n";
}
</programlisting></example>
     This example would display:
     <computeroutput>
fruits[a] = orange
fruits[d] = lemon
fruits[b] = banana
fruits[c] = apple
</computeroutput>
     The fruits have been sorted in reverse alphabetical order, and
     the index associated with each element has been maintained.
    <para>
     See also: <function>asort</function>, <function>rsort</function>,
     <function>ksort</function>, and <function>sort</function>.
   </refsect1>
  </refentry>

  <refentry id="function.asort">
   <refnamediv>
    <refname>asort</refname>
    <refpurpose>Sort an array and maintain index association</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>void <function>asort</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
    </funcsynopsis>
    <para>
     This function sorts an array such that array indices maintain their 
     correlation with the array elements they are associated with.  This is
     used mainly when sorting associative arrays where the actual element
     order is significant.  
     <example>
      <title><function>asort</function> example</title>
      <programlisting>
$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple");
asort($fruits);
for(reset($fruits); $key = key($fruits); next($fruits)) {
    echo "fruits[$key] = ".$fruits[$key]."\n";
}
</programlisting></example>
     This example would display:
     <computeroutput>
fruits[c] = apple
fruits[b] = banana
fruits[d] = lemon
fruits[a] = orange
</computeroutput>
     The fruits have been sorted in alphabetical order, and the index
     associated with each element has been maintained.
    <para>
     See also <function>arsort</function>, <function>rsort</function>,
     <function>ksort</function>, and <function>sort</function>.
   </refsect1>
  </refentry>

  <refentry id="function.count">
   <refnamediv>
    <refname>count</refname>
    <refpurpose>count elements in a variable</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>count</function></funcdef>
     <paramdef>mixed <parameter>var</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns the number of elements in <parameter>var</parameter>, which is 
     typically an array (since anything else will have one element).
    <para>
     Returns 0 if the variable is not set.
    <para>
     Returns 1 if the variable is not an array.
    <para>
     See also:
     <function>sizeof</function>, <function>isset</function>, and
     <function>is_array</function>.
   </refsect1>
  </refentry>

  <refentry id="function.current">
   <refnamediv>
    <refname>current</refname>
    <refpurpose>return the current element in an array</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>mixed <function>current</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
    </funcsynopsis>
    <para>
     Each array variable has an internal pointer that points to one of
     its elements.  In addition, all of the elements in the array are
     linked by a bidirectional linked list for traversing purposes.
     The internal pointer points to the first element that was inserted
     to the array until you run one of the functions that modify that
     pointer on that array.

    <para>
     The <function>current</function> function simply returns the
     array element that's currently being pointed by the internal
     pointer.  It does not move the pointer in any way.  If the
     internal pointer points beyond the end of the elements list,
     <function>current</function> returns false.

    <para> 
     <emphasis>Warning:</emphasis> if the array contains empty
     elements (0 or "", the empty string) then this function
     will return false for these elements as well. It is
     undecideable if the current element is just a zero-value or
     you have traversed beyond the end of the array. To properly
     traverse an array, use the <function>each</function>
     function.

    <para>
     See also:
     <function>end</function>, <function>next</function>,
     <function>prev</function> and <function>reset</function>.
   </refsect1>
  </refentry>


  <refentry id="function.each">
   <refnamediv>
    <refname>each</refname>
    <refpurpose>return next key/value pair from an array</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>array <function>each</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns the current key/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> each contain the key name of the array
     element, and <emphasis>1</emphasis> and
     <emphasis>value</emphasis> contain the data.
     
    <para>
     <example>
      <title>each() examples</title>
      <programlisting>
$foo = array( "bob", "fred", "jussi", "jouni" );
$bar = each( $foo );
      </programlisting>

      <para>
       <literal>$bar</literal> now contains the following key/value
       pairs:
       
       <itemizedlist spacing="compact">
        <listitem><simpara>0 => 0
        <listitem><simpara>1 => 'bob'
        <listitem><simpara>key => 0
        <listitem><simpara>value => 'bob'
       </itemizedlist>

       <programlisting>
$foo = array( "Robert" => "Bob", "Seppo" => "Sepi" );
$bar = each( $foo );
       </programlisting>

      <para>
       <literal>$bar</literal> now contains the following key/value
       pairs:

       <itemizedlist spacing="compact">
        <listitem><simpara>0 => 'Robert'
        <listitem><simpara>1 => 'Bob'
        <listitem><simpara>key => 'Robert'
        <listitem><simpara>value => 'Bob'
       </itemizedlist>

    </example>
      

    <para>
     <function>each</function> is typically used in conjunction with
     <function>list</function> to traverse an array; for instance,
     $HTTP_POST_VARS: 

     <example><title>Traversing $HTTP_POST_VARS with each()</title>
      <programlisting>
echo "Values submitted via POST method:&lt;br&gt;";
while ( list( $key, $val ) = each( $HTTP_POST_VARS ) ) {
   echo "$key => $val&lt;br&gt;";
}
      </programlisting>
     </example>

    <para>
     See also <function>key</function>, <function>current</function>,
     <function>reset</function>, <function>next</function>, and
     <function>prev</function>.

   </refsect1>
  </refentry>


  <refentry id="function.end">
   <refnamediv>
    <refname>end</refname>
    <refpurpose>set internal pointer of array to last element</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef><function>end</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>end</function> advances <parameter>array</parameter>'s
     internal pointer to the last element.
    <para>
     See also:
     <function>current</function>, <function>end</function>
     <function>next</function> and <function>reset</function>
   </refsect1>
  </refentry>

  <refentry id="function.key">
   <refnamediv>
    <refname>key</refname>
    <refpurpose>fetch a key from an associative array</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>mixed <function>key</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>key</function> returns the index element of the
     current array position.
    <para>
     See also:
     <function>current</function>
     <function>next</function>
   </refsect1>
  </refentry>


  <refentry id="function.ksort">
   <refnamediv>
    <refname>ksort</refname>
    <refpurpose>Sort an array by key.</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>ksort</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
    </funcsynopsis>
    
    <para>
     Sorts an array by key, maintaining key to data correlations. This
     is useful mainly for associative arrays.

    <example>
      <title><function>ksort</function> example</title>
      <programlisting>
$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple");
ksort($fruits);
for(reset($fruits); $key = key($fruits); next($fruits)) {
    echo "fruits[$key] = ".$fruits[$key]."\n";
}
</programlisting></example>
     This example would display:
     <computeroutput>
fruits[a] = orange
fruits[b] = banana
fruits[c] = apple
fruits[d] = lemon
</computeroutput>

    <simpara>
     See also <function>asort</function>, <function>arsort</function>, 
     <function>sort</function>, and <function>rsort</function>.

   </refsect1>
  </refentry>


  <refentry id="function.list">
   <refnamediv>
    <refname>list</refname>
    <refpurpose>
     assign variables as if they were an array
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>void <function>list</function></funcdef>
     <varargs>
    </funcsynopsis>
    <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.

     <example>
      <title><function>list</function> example</title>
      <programlisting>
&lt;table>
 &lt;tr>
  &lt;th>Employee name&lt;/th>
  &lt;th>Salary&lt;/th>
 &lt;/tr>
&lt;?php

$result = mysql($conn, "SELECT id, name, salary FROM employees");
while (list($id, $name, $salary) = mysql_fetch_row($result)) {
    print(" &lt;tr>\n".
          "  &lt;td>&lt;a href=\"info.php3?id=$id\">$name&lt;/a>&lt;/td>\n".
          "  &lt;td>$salary&lt;/td>\n".
          " &lt;/tr>\n");
}

?>&lt;/table>
</programlisting></example>

    <para>
     See also:
     <function>array</function>.
   </refsect1>
  </refentry>

  <refentry id="function.next">
   <refnamediv>
    <refname>next</refname>
    <refpurpose>advance the internal array pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>mixed <function>next</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns the array element in the next place that's pointed by the
     internal array pointer, or false if there are no more elements.
     <emphasis>Warning:</emphasis> if the array contains empty
     elements then this function will return false for these elements as
     well.  To properly traverse an array which may contain empty elements
     see the <function>each</function> function. 
    <para>
     <function>next</function> behaves like
      <function>current</function>, with one difference.  It advances
      the internal array pointer one place forward before returning
      the element.  That means it returns the next array element and
      advances the internal array pointer by one.  If advancing the
      internal array pointer results in going beyond the end of the
      element list, <function>next</function> returns false.

    <para>
     See also:
     <function>current</function>, <function>end</function>
     <function>prev</function> and <function>reset</function>
   </refsect1>
  </refentry>

  <refentry id="function.pos">
   <refnamediv>
    <refname>pos</refname>
    <refpurpose>return the current element in an array</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>mixed <function>pos</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
    </funcsynopsis>
    <simpara>
	This is an alias for <function>current</function>.
    <para>
     See also:
     <function>end</function>, <function>next</function>,
     <function>prev</function> and <function>reset</function>.
   </refsect1>
  </refentry>

  <refentry id="function.prev">
   <refnamediv>
    <refname>prev</refname>
    <refpurpose>rewind internal array pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>mixed <function>prev</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns the array element in the previous place that's pointed by
     the internal array pointer, or false if there are no more
     elements. <emphasis>Warning:</emphasis> if the array contains empty
	 elements then this function will return false for these elements as
	 well.  To properly traverse an array which may contain empty elements
	 see the <function>each</function> function.
    <para>  
     <function>prev</function> behaves just like
     <function>next</function>, except it rewinds the internal array
     pointer one place instead of advancing it.
    <para>
     See also:
     <function>current</function>, <function>end</function>
     <function>next</function> and <function>reset</function>
   </refsect1>
  </refentry>

  <refentry id="function.reset">
   <refnamediv>
    <refname>reset</refname>
    <refpurpose>set internal pointer of array to first element</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef><function>reset</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>reset</function> rewinds <parameter>array</parameter>'s
     internal pointer to the first element.
    <para>
     See also:
     <function>current</function>, <function>next</function>
     <function>prev</function> and <function>reset</function>
   </refsect1>
  </refentry>

  <refentry id="function.rsort">
   <refnamediv>
    <refname>rsort</refname>
    <refpurpose>Sort an array in reverse order</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>void <function>rsort</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
    </funcsynopsis>
    <para>
	This function sorts an array in reverse order (highest to lowest).
	<example>
      <title><function>rsort</function> example</title>
	<programlisting>
    $fruits = array("lemon","orange","banana","apple");
    rsort($fruits);
    for(reset($fruits); $key = key($fruits); next($fruits)) {
        echo "fruits[$key] = ".$fruits[$key]."\n";
    }
	</programlisting></example>
	This example would display:
	<computeroutput>
	fruits[0] = orange
	fruits[1] = lemon
	fruits[2] = banana
	fruits[3] = apple
	</computeroutput>
	The fruits have been sorted in reverse alphabetical order.
    <para>
     See also <function>arsort</function>, <function>asort</function>,
     <function>ksort</function>, <function>sort</function> and <function>usort</function>.
   </refsect1>
  </refentry>

  <refentry id="function.sizeof">
   <refnamediv>
    <refname>sizeof</refname>
    <refpurpose>get size of array</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>sizeof</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns the number of elements in the array.
    <para>
     See also:
     <function>count</function>
   </refsect1>
  </refentry>

  <refentry id="function.sort">
   <refnamediv>
    <refname>sort</refname>
    <refpurpose>Sort an array</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>void <function>sort</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
    </funcsynopsis>
    <para>
     This function sorts an array.  Elements will be arranged from lowest to
     highest when this function has completed.
     <example>
      <title><function>sort</function> example</title>
	<programlisting>
$fruits = array("lemon","orange","banana","apple");
sort($fruits);
for(reset($fruits); $key = key($fruits); next($fruits)) {
    echo "fruits[$key] = ".$fruits[$key]."\n";
}
</programlisting></example>
     This example would display:
     <computeroutput>
fruits[0] = apple
fruits[1] = banana
fruits[2] = lemon
fruits[3] = orange
</computeroutput>
     The fruits have been sorted in alphabetical order.
    <para>
     See also <function>arsort</function>, <function>asort</function>,
     <function>ksort</function>, <function>rsort</function>, and <function>usort</function>.
   </refsect1>
  </refentry>

  <refentry id="function.usort">
   <refnamediv>
    <refname>usort</refname>
    <refpurpose>Sort an array using a user-define comparison function</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>void <function>usort</function></funcdef>
     <paramdef>array <parameter>array</parameter></paramdef>
     <paramdef>function <parameter>cmp_function</parameter></paramdef>
    </funcsynopsis>
    <para>
     This function will sort an array using a user-supplied comparison function.
	 If the array you wish to sort needs to be sorted by some non-trivial
	 criteria, you should use this function.
     <example>
      <title><function>usort</function> example</title>
	<programlisting>
function cmp($a,$b) {   
    if($a==$b) return 0;
    return ($a>$b) ? -1:1;
}
$a = array(3,2,5,6,1);
usort($a,cmp);
while(list($key,$value) = each($a)) {
    echo "$key: $value\n";
}
</programlisting></example>
     This example would display:
     <computeroutput>
0: 6
1: 5
2: 3
3: 2
4: 1
</computeroutput>
     Obviously in this trivial case the <function>rsort</function> function
	 would be more appropriate.
    <para>
     See also <function>arsort</function>, <function>asort</function>,
     <function>ksort</function>, <function>rsort</function> and <function>sort</function>.
   </refsect1>
  </refentry>

 </reference>

<!-- 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
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->