cvs: phpdoc /nl/functions array.xml

manuzhai Wed Apr 10 09:54:05 2002 EDT Modified files: /phpdoc/nl/functions array.xml Log: Anticipating file split.

Index: phpdoc/nl/functions/array.xml diff -u /dev/null phpdoc/nl/functions/array.xml:1.6 --- /dev/null Wed Apr 10 09:54:05 2002 +++ phpdoc/nl/functions/array.xml Wed Apr 10 09:54:05 2002 @@ -0,0 +1,4002 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- EN-Revision: 1.172 Maintainer: manuzhai Status: partial --> + <reference id="ref.array"> + <title>Array Functies</title> + <titleabbrev>Arrays</titleabbrev> + + <partintro> + <para id="array.intro"> + Deze functies maken het gebruik en de manipulatie van arrays + mogelijk op verschillende manieren. Arrays zijn essentieel + voor het bewaren en beheren van sets van variabelen. + </para> + <para> + Simpele en multi-dimensionelale arrays worden ondersteund, en + kunnen door gebruikers of een andere functie worden gemaakt. + Er zijn specifieke database handling functies die arrays + invullen aan de hand van database queries, en verschillende + functies geven arrays terug. + </para> + <para> + Je kunt de <link linkend="language.types.array">Arrays</link> + sectie van de manual bekijken voor een gedetailleerde uitleg over + hoe arrays worden geimplementeerd en gebruikt in PHP. + </para> + + <section id="array.requirements"> + <title>Benodigdheden</title> + <para> + Deze functies zijn beschikbaar als deel van een standaard module, die + altijd beschikbaar is. + </para> + </section> + + <section id="array.installation"> + <title>Installatie</title> + <para> + Er is geen installatie nodig om deze functies te gebruiken, ze zijn deel + van de PHP kern. + </para> + </section> + + <section id="array.configuration"> + <title>Runtime Configuratie</title> + &no.config; + </section> + + <section id="array.resources"> + <title>Resource types</title> + &no.resource; + </section> + + <section id="array.constants"> + <title>Predefined constanten</title> + <para> + <constant>CASE_UPPER</constant> en <constant>CASE_LOWER</constant> worden + gebruikt bij de <function>array_change_key_case</function> functie. Ze + worden respectievelijk gebruikt om een string naar upper case of lower + case te veranderen. + </para> + </section> + + <section id="array.seealso"> + <title>Zie ook</title> + <para> + Zie ook: <function>is_array</function>, <function>explode</function>, + <function>implode</function>, <function>split</function>, + <function>join</function>. + </para> + </section> + </partintro> + + <refentry id="function.array"> + <refnamediv> + <refname>array</refname> + <refpurpose> + Maak een array + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array</methodname> + <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam> + </methodsynopsis> + <para> + Geeft een array van de parameters terug. De parameters kan een + index worden gegeven met de <literal>=&gt;</literal> operator. + </para> + <para> + <note> + <para> + <function>array</function> is een language construct + dat wordt gebruikt om arrays letterlijk te beschrijven, en is + geen gewone functie. + </para> + </note> + </para> + <para> + Syntax "index =&gt; waarde", gescheiden door komma's definieren + index en waarden. index mag een string of numeriek zijn. Wanneer + de index wordt weggelaten wordt er automatisch een integer index + gegenereerd, beginnnend bij 0. Als index een integer is, zal de + volgende gegenereerde index de grootste integer index + 1 zijn. Let + er op dat wanneer twee identieke index worden gedefinieerd, de + laatste de eerste zal overschrijven. + </para> + <para> + Het volgende voorbeeld demonstreert hoe een twee-dimensionale + array kan worden gemaakt, hoe je keys voor associatieve + arrays kunt specificeren, en hoe je numerieke indexen kunt + overslaan in normale arrays. + <example> + <title><function>array</function> voorbeeld</title> + <programlisting role="php"> +<![CDATA[ +$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> + <para> + <example> + <title>Automatische index met <function>array</function></title> + <programlisting role="php"> +<![CDATA[ +$array = array( 1, 1, 1, 1, 1, 8=>1, 4=>1, 19, 3=>13); +print_r($array); +]]> + </programlisting> + <para> + will display : + <screen role="php"> +<![CDATA[ +Array +( + [0] => 1 + [1] => 1 + [2] => 1 + [3] => 13 + [4] => 1 + [8] => 1 + [9] => 19 +) +]]> + </screen> + </para> + </example> + Let er op dat index '3' twee keer wordt gedefinieerd, en zijn laatste + waarde van 13 behoudt. Index 4 wordt gedefinieerd na index 8, en de + volgende index (met waarde 19) is 0, omdat de grootste index 8 was. + </para> + <para> + Dit voorbeeld maakt een 1-based array. + <example> + <title>1-based index met <function>array</function></title> + <programlisting role="php"> +<![CDATA[ +$firstquarter = array(1 => 'January', 'February', 'March'); +print_r($firstquarter); +]]> + </programlisting> + <para> + will display : + <screen> +<![CDATA[ +Array +( + [1] => 'January' + [2] => 'February' + [3] => 'March' +) +]]> + </screen> + </para> + </example> + </para> + <para> + Zie ook <function>array_pad</function>, + <function>list</function>, <function>range</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-change-key-case"> + <refnamediv> + <refname>array_change_key_case</refname> + <refpurpose>Returns an array with all string keys lowercased or uppercased</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_change_key_case</methodname> + <methodparam><type>array</type><parameter>input</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>case</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_change_key_case</function> changes the + keys in the <parameter>input</parameter> array to + be all lowercase or uppercase. The change depends + on the last optional <parameter>case</parameter> + parameter. You can pass two constants there, + <constant>CASE_UPPER</constant> and + <constant>CASE_LOWER</constant>. The default is + <constant>CASE_LOWER</constant>. The function will leave + number indices as is. + </para> + <example> + <title><function>array_change_key_case</function> example</title> + <programlisting role="php"> +<![CDATA[ +$input_array = array("FirSt" => 1, "SecOnd" => 4); +print_r(array_change_key_case($input_array, CASE_UPPER)); +]]> + </programlisting> + <para> + The printout of the above program will be: + <screen> +<![CDATA[ +Array +( + [FIRST] => 1 + [SECOND] => 2 +) +]]> + </screen> + </para> + </example> + </refsect1> + </refentry> + + <refentry id="function.array-chunk"> + <refnamediv> + <refname>array_chunk</refname> + <refpurpose>Split an array into chunks</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_chunk</methodname> + <methodparam><type>array</type><parameter>input</parameter></methodparam> + <methodparam><type>int</type><parameter>size</parameter></methodparam> + <methodparam choice="opt"><type>bool</type><parameter>preserve_keys</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_chunk</function> splits the array into + several arrays with <parameter>size</parameter> values + in them. You may also have an array with less values + at the end. You get the arrays as members of a + multidimensional array indexed with numbers starting + from zero. + </para> + <para> + By setting the optional <parameter>preserve_keys</parameter> + parameter to &true;, you can force PHP to preserve the original + keys from the input array. If you specify &false; new number + indices will be used in each resulting array with + indices starting from zero. The default is &false;. + </para> + <example> + <title><function>array_chunk</function> example</title> + <programlisting role="php"> +<![CDATA[ +$input_array = array('a', 'b', 'c', 'd', 'e'); +print_r(array_chunk($input_array, 2)); +print_r(array_chunk($input_array, 2, TRUE)); +]]> + </programlisting> + <para> + The printout of the above program will be: + <screen> +<![CDATA[ +Array +( + [0] => Array + ( + [0] => a + [1] => b + ) + + [1] => Array + ( + [0] => c + [1] => d + ) + + [2] => Array + ( + [0] => e + ) + +) +Array +( + [0] => Array + ( + [0] => a + [1] => b + ) + + [1] => Array + ( + [2] => c + [3] => d + ) + + [2] => Array + ( + [4] => e + ) + +) +]]> + </screen> + </para> + </example> + </refsect1> + </refentry> + + <refentry id="function.array-count-values"> + <refnamediv> + <refname>array_count_values</refname> + <refpurpose>Counts all the values of an array</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_count_values</methodname> + <methodparam><type>array</type><parameter>input</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_count_values</function> returns an array using + the values of the <parameter>input</parameter> array as keys and + their frequency in <parameter>input</parameter> as values. + </para> + <para> + <example> + <title><function>array_count_values</function> example</title> + <programlisting role="php"> +<![CDATA[ +$array = array (1, "hello", 1, "world", "hello"); +print_r(array_count_values ($array)); +]]> + </programlisting> + <para> + The printout of the above program will be: + <screen> +<![CDATA[ +Array +( + [1] => 2 + [hello] => 2 + [world] => 1 +) +]]> + </screen> + </para> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-diff"> + <refnamediv> + <refname>array_diff</refname> + <refpurpose>Computes the difference of arrays</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_diff</methodname> + <methodparam><type>array</type><parameter>array1</parameter></methodparam> + <methodparam><type>array</type><parameter>array2</parameter></methodparam> + <methodparam choice="opt"><type>array</type><parameter> ...</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_diff</function> returns an array + containing all the values of <parameter>array1</parameter> + that are not present in any of the other arguments. + Note that keys are preserved. + </para> + <para> + <example> + <title><function>array_diff</function> example</title> + <programlisting role="php"> +<![CDATA[ +$array1 = array ("a" => "green", "red", "blue", "red"); +$array2 = array ("b" => "green", "yellow", "red"); +$result = array_diff ($array1, $array2); +]]> + </programlisting> + </example> + </para> + <para> + This makes <varname>$result</varname> have + <literal>array ("blue");</literal>. Multiple occurrences in + $array1 are all treated the same way. + </para> + <note> + <simpara> + Two elements are considered equal if and only if + <literal>(string) $elem1 === (string) $elem2</literal>. In words: + when the string representation is the same. + <!-- TODO: example of it... --> + </simpara> + </note> + <warning> + <simpara> + This was broken in PHP 4.0.4! + <!-- TODO: when exactly was this broken?... --> + </simpara> + </warning> + <para> + See also <function>array_intersect</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-filter"> + <refnamediv> + <refname>array_filter</refname> + <refpurpose> + Filters elements of an array using a callback function + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_filter</methodname> + <methodparam><type>array</type><parameter>input</parameter></methodparam> + <methodparam choice="opt"><type>mixed</type><parameter>callback</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_filter</function> returns an array + containing all the elements of <parameter>input</parameter> + filtered according a callback function. If the + <parameter>input</parameter> is an associative array + the keys are preserved. + </para> + <para> + <example> + <title><function>array_filter</function> example</title> + <programlisting role="php"> +<![CDATA[ +function odd($var) { + return ($var % 2 == 1); +} + +function even($var) { + return ($var % 2 == 0); +} + +$array1 = array ("a"=>1, "b"=>2, "c"=>3, "d"=>4, "e"=>5); +$array2 = array (6, 7, 8, 9, 10, 11, 12); + +echo "Odd :\n"; +print_r(array_filter($array1, "odd")); +echo "Even:\n"; +print_r(array_filter($array2, "even")); +]]> + </programlisting> + <para> + The printout of the program above will be: + <screen role="php"> +<![CDATA[ +Odd : +Array +( + [a] => 1 + [c] => 3 + [e] => 5 +) +Even: +Array +( + [0] => 6 + [2] => 8 + [4] => 10 + [6] => 12 +) +]]> + </screen> + </para> + </example> + </para> + &note.func-callback; + <para> + Users may not change the array itself from the callback + function. e.g. Add/delete an element, unset the array that + <function>array_filter</function> is applied to. If the array + is changed, the behavior of this function is undefined. + </para> + <para> + See also <function>array_map</function> and + <function>array_reduce</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-flip"> + <refnamediv> + <refname>array_flip</refname> + <refpurpose>Flip all the values of an array</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_flip</methodname> + <methodparam><type>array</type><parameter>trans</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_flip</function> returns an <type>array</type> in flip + order, i.e. keys from <parameter>trans</parameter> become values and + <parameter>trans</parameter>'s values become keys. + </para> + <para> + Note that the values of <parameter>trans</parameter> need to be valid + keys, i.e. they need to be either <type>integer</type> or + <type>string</type>. A warning will be emitted if a value has the wrong + type, and the key/value pair in question <emphasis>will not be + flipped</emphasis>. + </para> + <para> + If a value has several occurrences, the latest key will be + used as its values, and all others will be lost. + </para> + <para> + <function>array_flip</function> returns &false; + if it fails. + </para> + <para> + <example> + <title><function>array_flip</function> example</title> + <programlisting role="php"> +<![CDATA[ +$trans = array_flip ($trans); +$original = strtr ($str, $trans); +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title><function>array_flip</function> example : collision</title> + <programlisting role="php"> +<![CDATA[ +$trans = array ("a" => 1, "b" => 1, "c" => 2); +$trans = array_flip ($trans); +print_r($trans); +]]> + </programlisting> + <para> + now $trans is : + <screen> +<![CDATA[ +Array +( + [1] => b + [2] => c +) +]]> + </screen> + </para> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-fill"> + <refnamediv> + <refname>array_fill</refname> + <refpurpose>Fill an array with values</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_fill</methodname> + <methodparam><type>int</type><parameter>start_index</parameter></methodparam> + <methodparam><type>int</type><parameter>num</parameter></methodparam> + <methodparam><type>mixed</type><parameter>value</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_fill</function> fills an array with + <parameter>num</parameter> entries of the value of the + <parameter>value</parameter> parameter, keys starting at the + <parameter>start_index</parameter> parameter. + </para> + <para> + <example> + <title><function>array_fill</function> example</title> + <programlisting role="php"> +<![CDATA[ +$a = array_fill(5, 6, 'banana'); +]]> + </programlisting> + <para> + $a now has the following entries using <function>print_r</function>: + <screen> +<![CDATA[ +Array +( + [5] => banana + [6] => banana + [7] => banana + [8] => banana + [9] => banana + [10] => banana +) +]]> + </screen> + </para> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-intersect"> + <refnamediv> + <refname>array_intersect</refname> + <refpurpose>Computes the intersection of arrays</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_intersect</methodname> + <methodparam><type>array</type><parameter>array1</parameter></methodparam> + <methodparam><type>array</type><parameter>array2</parameter></methodparam> + <methodparam choice="opt"><type>array</type><parameter> ...</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_intersect</function> returns an array + containing all the values of <parameter>array1</parameter> + that are present in all the arguments. + Note that keys are preserved. + </para> + <para> + <example> + <title><function>array_intersect</function> example</title> + <programlisting role="php"> +<![CDATA[ +$array1 = array ("a" => "green", "red", "blue"); +$array2 = array ("b" => "green", "yellow", "red"); +$result = array_intersect ($array1, $array2); +]]> + </programlisting> + <para> + This makes <varname>$result</varname> have + <screen role="php"> +<![CDATA[ +Array +( + [a] => green + [0] => red +) +]]> + </screen> + </para> + </example> + </para> + <note> + <simpara> + Two elements are considered equal if and only if + <literal>(string) $elem1 === (string) $elem2</literal>. In words: + when the string representation is the same. + <!-- TODO: example of it... --> + </simpara> + </note> + <warning> + <simpara> + This was broken in PHP 4.0.4! + <!-- TODO: when exactly was this broken?... --> + </simpara> + </warning> + <para> + See also <function>array_diff</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-key-exists"> + <refnamediv> + <refname>array_key_exists</refname> + <refpurpose>Checks if the given key or index exists in the array</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>bool</type><methodname>array_key_exists</methodname> + <methodparam><type>mixed</type><parameter>key</parameter></methodparam> + <methodparam><type>array</type><parameter>search</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_key_exists</function> returns &true; if the + given <parameter>key</parameter> is set in the array. + <parameter>key</parameter> can be any value possible + for an array index. + </para> + <para> + <example> + <title><function>array_key_exists</function> example</title> + <programlisting role="php"> +<![CDATA[ +$search_array = array("first" => 1, "second" => 4); +if (array_key_exists("first", $search_array)) { + echo "The 'first' element is in the array"; +} +]]> + </programlisting> + </example> + </para> + <note> + <simpara> + This name of this function is <function>key_exists</function> + in PHP version 4.0.6. + </simpara> + </note> + <para> + See also <function>isset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-keys"> + <refnamediv> + <refname>array_keys</refname> + <refpurpose>Return all the keys of an array</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_keys</methodname> + <methodparam><type>array</type><parameter>input</parameter></methodparam> + <methodparam choice="opt"><type>mixed</type><parameter> + search_value + </parameter></methodparam> + </methodsynopsis> + <para> + <function>array_keys</function> returns the keys, numeric and + string, from the <parameter>input</parameter> array. + </para> + <para> + If the optional <parameter>search_value</parameter> is specified, + then only the keys for that value are returned. Otherwise, all + the keys from the <parameter>input</parameter> are returned. + </para> + <para> + <example> + <title><function>array_keys</function> example</title> + <programlisting role="php"> +<![CDATA[ +$array = array (0 => 100, "color" => "red"); +print_r(array_keys ($array)); + +$array = array ("blue", "red", "green", "blue", "blue"); +print_r(array_keys ($array, "blue")); + +$array = array ("color" => array("blue", "red", "green"), "size" => array("small", "medium", "large")); +print_r(array_keys ($array)); +]]> + </programlisting> + <para> + The printout of the program above will be: + <screen> +<![CDATA[ +Array +( + [0] => 0 + [1] => color +) +Array +( + [0] => 0 + [1] => 3 + [2] => 4 +) +Array +( + [0] => color + [1] => size +) +]]> + </screen> + </para> + </example> + </para> + <note> + <para> + This function was added to PHP 4, below is an implementation for + those still using PHP 3. + <example> + <title> + Implementation of <function>array_keys</function> for PHP 3 + users + </title> + <programlisting role="php"> +<![CDATA[ +function array_keys ($arr, $term="") { + $t = array(); + while (list($k,$v) = each($arr)) { + if ($term && $v != $term) { + continue; + } + $t[] = $k; + } + return $t; +} +]]> + </programlisting> + </example> + </para> + </note> + <para> + See also <function>array_values</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-map"> + <refnamediv> + <refname>array_map</refname> + <refpurpose> + Applies the callback to the elements of the given arrays + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_map</methodname> + <methodparam><type>mixed</type><parameter>callback</parameter></methodparam> + <methodparam><type>array</type><parameter>arr1</parameter></methodparam> + <methodparam choice="opt"><type>array</type><parameter>arr2...</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_map</function> returns an array containing all + the elements of <parameter>arr1</parameter> after applying the + callback function to each one. The number of parameters that the + callback function accepts should match the number of arrays + passed to the <function>array_map</function> + </para> + <para> + <example> + <title><function>array_map</function> example</title> + <programlisting role="php"> +<![CDATA[ +function cube($n) { + return $n*$n*$n; +} + +$a = array(1, 2, 3, 4, 5); +$b = array_map("cube", $a); +print_r($b); +]]> + </programlisting> + <para> + This makes <varname>$b</varname> have: + <screen> +<![CDATA[ +Array +( + [0] => 1 + [1] => 8 + [2] => 27 + [3] => 64 + [4] => 125 +) +]]> + </screen> + </para> + </example> + </para> + <para> + <example> + <title><function>array_map</function> - using more arrays</title> + <programlisting role="php"> +<![CDATA[ +function show_Spanish($n, $m) { + return "The number $n is called $m in Spanish"; +} + +function map_Spanish($n, $m) { + return array ($n => $m); +} + +$a = array(1, 2, 3, 4, 5); +$b = array("uno", "dos", "tres", "cuatro", "cinco"); + +$c = array_map("show_Spanish", $a, $b); +print_r($c); + +$d = array_map("map_Spanish", $a , $b); +print_r($d); +]]> + </programlisting> + <para> + This results: + <screen> +<![CDATA[ +// printout of $c +Array +( + [0] => The number 1 is called uno in Spanish + [1] => The number 2 is called dos in Spanish + [2] => The number 3 is called tres in Spanish + [3] => The number 4 is called cuatro in Spanish + [4] => The number 5 is called cinco in Spanish +) + +// printout of $d +Array +( + [0] => Array + ( + [1] => uno + ) + + [1] => Array + ( + [2] => dos + ) + + [2] => Array + ( + [3] => tres + ) + + [3] => Array + ( + [4] => cuatro + ) + + [4] => Array + ( + [5] => cinco + ) + +) +]]> + </screen> + </para> + </example> + </para> + <para> + Usually when using two or more arrays, they should be of equal length + because the callback function is applied in parallel to the corresponding + elements. + If the arrays are of unequal length, the shortest one will be extended + with empty elements. + </para> + <para> + An interesting use of this function is to construct an array of arrays, + which can be easily performed by using &null; + as the name of the callback function + </para> + <para> + <example> + <title>Creating an array of arrays</title> + <programlisting role="php"> +<![CDATA[ +$a = array(1, 2, 3, 4, 5); +$b = array("one", "two", "three", "four", "five"); +$c = array("uno", "dos", "tres", "cuatro", "cinco"); + +$d = array_map(null, $a, $b, $c); +print_r($d); +]]> + </programlisting> + </example> + </para> + <para> + The printout of the program above will be: + <screen> +<![CDATA[ +Array +( + [0] => Array + ( + [0] => 1 + [1] => one + [2] => uno + ) + + [1] => Array + ( + [0] => 2 + [1] => two + [2] => dos + ) + + [2] => Array + ( + [0] => 3 + [1] => three + [2] => tres + ) + + [3] => Array + ( + [0] => 4 + [1] => four + [2] => cuatro + ) + + [4] => Array + ( + [0] => 5 + [1] => five + [2] => cinco + ) + +) +]]> + </screen> + </para> + <para> + See also <function>array_filter</function> and + <function>array_reduce</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-merge"> + <refnamediv> + <refname>array_merge</refname> + <refpurpose>Merge two or more arrays</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_merge</methodname> + <methodparam><type>array</type><parameter>array1</parameter></methodparam> + <methodparam><type>array</type><parameter>array2</parameter></methodparam> + <methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_merge</function> merges the elements of two or + more arrays together so that the values of one are appended to + the end of the previous one. It returns the resulting array. + </para> + <para> + If the input arrays have the same string keys, then the later + value for that key will overwrite the previous one. If, however, + the arrays have the same numeric key, the later value will not + overwrite the original value, but will be appended. + </para> + <para> + <example> + <title><function>array_merge</function> example</title> + <programlisting role="php"> +<![CDATA[ +$array1 = array ("color" => "red", 2, 4); +$array2 = array ("a", "b", "color" => "green", "shape" => "trapezoid", 4); +$result = array_merge ($array1, $array2); +]]> + </programlisting> + <para> + The <literal>$result</literal> will be: + <screen role="php"> +<![CDATA[ +Array +( + [color] => green + [0] => 2 + [1] => 4 + [2] => a + [3] => b + [shape] => trapezoid + [4] => 4 +) +]]> + </screen> + </para> + </example> + </para> + <para> + See also <function>array_merge_recursive</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-merge-recursive"> + <refnamediv> + <refname>array_merge_recursive</refname> + <refpurpose>Merge two or more arrays recursively</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_merge_recursive</methodname> + <methodparam><type>array</type><parameter>array1</parameter></methodparam> + <methodparam><type>array</type><parameter>array2</parameter></methodparam> + <methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_merge_recursive</function> merges the elements of + two or more arrays together so that the values of one are appended + to the end of the previous one. It returns the resulting array. + </para> + <para> + If the input arrays have the same string keys, then the values for + these keys are merged together into an array, and this is done + recursively, so that if one of the values is an array itself, the + function will merge it with a corresponding entry in another array + too. If, however, the arrays have the same numeric key, the later + value will not overwrite the original value, but will be appended. + </para> + <para> + <example> + <title><function>array_merge_recursive</function> example</title> + <programlisting role="php"> +<![CDATA[ +$ar1 = array ("color" => array ("favorite" => "red"), 5); +$ar2 = array (10, "color" => array ("favorite" => "green", "blue")); +$result = array_merge_recursive ($ar1, $ar2); +]]> + </programlisting> + <para> + The <literal>$result</literal> will be: + <screen role="php"> +<![CDATA[ +Array +( + [color] => Array + ( + [favorite] => Array + ( + [0] => red + [1] => green + ) + + [0] => blue + ) + + [0] => 5 + [1] => 10 +) +]]> + </screen> + </para> + </example> + </para> + <para> + See also <function>array_merge</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-multisort"> + <refnamediv> + <refname>array_multisort</refname> + <refpurpose>Sort multiple or multi-dimensional arrays</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>bool</type><methodname>array_multisort</methodname> + <methodparam><type>array</type><parameter>ar1</parameter></methodparam> + <methodparam choice="opt"><type>mixed</type><parameter>arg</parameter></methodparam> + <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam> + <methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_multisort</function> can be used to sort several + arrays at once or a multi-dimensional array according by one of + more dimensions. It maintains key association when sorting. + </para> + <para> + The input arrays are treated as columns of a table to be sorted + by rows - this resembles the functionality of SQL ORDER BY + clause. The first array is the primary one to sort by. The rows + (values) in that array that compare the same are sorted by the + next input array, and so on. + </para> + <para> + The argument structure of this function is a bit unusual, but + flexible. The very first argument has to be an + array. Subsequently, each argument can be either an array or a + sorting flag from the following lists. + </para> + <para> + Sorting order flags: + <itemizedlist> + <listitem> + <simpara>SORT_ASC - sort in ascending order</simpara> + </listitem> + <listitem> + <simpara>SORT_DESC - sort in descending order</simpara> + </listitem> + </itemizedlist> + </para> + <para> + Sorting type flags: + <itemizedlist> + <listitem> + <simpara>SORT_REGULAR - compare items normally</simpara> + </listitem> + <listitem> + <simpara>SORT_NUMERIC - compare items numerically</simpara> + </listitem> + <listitem> + <simpara>SORT_STRING - compare items as strings</simpara> + </listitem> + </itemizedlist> + </para> + <para> + No two sorting flags of the same type can be specified after each + array. The sorting flags specified after an array argument apply + only to that array - they are reset to default SORT_ASC and + SORT_REGULAR after before each new array argument. + </para> + <para> + Returns &true; on success, &false; + on failure. + </para> + <para> + <example> + <title>Sorting multiple arrays</title> + <programlisting role="php"> +<![CDATA[ +$ar1 = array ("10", 100, 100, "a"); +$ar2 = array (1, 3, "2", 1); +array_multisort ($ar1, $ar2); +]]> + </programlisting> + </example> + </para> + <para> + In this example, after sorting, the first array will contain 10, + "a", 100, 100. The second array will contain 1, 1, "2", 3. The + entries in the second array corresponding to the identical + entries in the first array (100 and 100) were sorted as well. + </para> + <para> + <example> + <title>Sorting multi-dimensional array</title> + <programlisting role="php"> +<![CDATA[ +$ar = array (array ("10", 100, 100, "a"), array (1, 3, "2", 1)); +array_multisort ($ar[0], SORT_ASC, SORT_STRING, + $ar[1], SORT_NUMERIC, SORT_DESC); +]]> + </programlisting> + </example> + </para> + <para> + In this example, after sorting, the first array will contain 10, + 100, 100, "a" (it was sorted as strings in ascending order), and + the second one will contain 1, 3, "2", 1 (sorted as numbers, in + descending order). + </para> + </refsect1> + </refentry> + + <refentry id="function.array-pad"> + <refnamediv> + <refname>array_pad</refname> + <refpurpose> + Pad array to the specified length with a value + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_pad</methodname> + <methodparam><type>array</type><parameter>input</parameter></methodparam> + <methodparam><type>int</type><parameter>pad_size</parameter></methodparam> + <methodparam><type>mixed</type><parameter>pad_value</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_pad</function> returns a copy of the + <parameter>input</parameter> padded to size specified by + <parameter>pad_size</parameter> with value + <parameter>pad_value</parameter>. If + <parameter>pad_size</parameter> is positive then the array is + padded on the right, if it's negative then on the left. If the + absolute value of <parameter>pad_size</parameter> is less than or + equal to the length of the <parameter>input</parameter> then no + padding takes place. + </para> + <para> + <example> + <title><function>array_pad</function> example</title> + <programlisting role="php"> +<![CDATA[ +$input = array (12, 10, 9); + +$result = array_pad ($input, 5, 0); +// result is array (12, 10, 9, 0, 0) + +$result = array_pad ($input, -7, -1); +// result is array (-1, -1, -1, -1, 12, 10, 9) + +$result = array_pad ($input, 2, "noop"); +// not padded +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-pop"> + <refnamediv> + <refname>array_pop</refname> + <refpurpose>Pop the element off the end of array</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>mixed</type><methodname>array_pop</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_pop</function> pops and returns the last value of + the <parameter>array</parameter>, shortening the + <parameter>array</parameter> by one element. + If <parameter>array</parameter> is empty (or is not an array), + &null; will be returned. + </para> + <para> + <example> + <title><function>array_pop</function> example</title> + <programlisting role="php"> +<![CDATA[ +$stack = array ("orange", "banana", "apple", "raspberry"); +$fruit = array_pop ($stack); +]]> + </programlisting> + <para> + After this, <varname>$stack</varname> will have only 3 elements: + <screen role="php"> +<![CDATA[ +Array +( + [0] => orange + [1] => banana + [2] => apple +) +]]> + </screen> + and <literal>rasberry</literal> will be assigned to + <varname>$fruit</varname>. + </para> + </example> + </para> + &return.falseproblem; + <para> + See also <function>array_push</function>, + <function>array_shift</function>, and + <function>array_unshift</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-push"> + <refnamediv> + <refname>array_push</refname> + <refpurpose> + Push one or more elements onto the end of array + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>int</type><methodname>array_push</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + <methodparam><type>mixed</type><parameter>var</parameter></methodparam> + <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_push</function> treats + <parameter>array</parameter> as a stack, and pushes the passed + variables onto the end of <parameter>array</parameter>. The + length of <parameter>array</parameter> increases by the number of + variables pushed. Has the same effect as: + <programlisting role="php"> +<![CDATA[ +$array[] = $var; +]]> + </programlisting> + repeated for each <parameter>var</parameter>. + </para> + <para> + Returns the new number of elements in the array. + </para> + <para> + <example> + <title><function>array_push</function> example</title> + <programlisting role="php"> +<![CDATA[ +$stack = array ("orange", "banana"); +array_push ($stack, "apple", "raspberry"); +]]> + </programlisting> + <para> + This example would result in <varname>$stack</varname> having + the following elements: + <screen role="php"> +<![CDATA[ +Array +( + [0] => orange + [1] => banana + [2] => apple + [3] => raspberry +) +]]> + </screen> + </para> + </example> + </para> + <para> + See also <function>array_pop</function>, + <function>array_shift</function>, and + <function>array_unshift</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-rand"> + <refnamediv> + <refname>array_rand</refname> + <refpurpose> + Pick one or more random entries out of an array + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>mixed</type><methodname>array_rand</methodname> + <methodparam><type>array</type><parameter>input</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>num_req</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_rand</function> is rather useful when you want to + pick one or more random entries out of an array. It takes an + <parameter>input</parameter> array and an optional argument + <parameter>num_req</parameter> which specifies how many entries you + want to pick - if not specified, it defaults to 1. + </para> + <para> + If you are picking only one entry, <function>array_rand</function> + returns the key for a random entry. Otherwise, it returns an array + of keys for the random entries. This is done so that you can pick + random keys as well as values out of the array. + </para> + <para> + Don't forget to call <function>srand</function> to seed the random + number generator. + </para> + <para> + <example> + <title><function>array_rand</function> example</title> + <programlisting role="php"> +<![CDATA[ +srand ((float) microtime() * 10000000); +$input = array ("Neo", "Morpheus", "Trinity", "Cypher", "Tank"); +$rand_keys = array_rand ($input, 2); +print $input[$rand_keys[0]]."\n"; +print $input[$rand_keys[1]]."\n"; +]]> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-reverse"> + <refnamediv> + <refname>array_reverse</refname> + <refpurpose> + Return an array with elements in reverse order + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_reverse</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + <methodparam choice="opt"><type>bool</type><parameter>preserve_keys</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_reverse</function> takes input + <parameter>array</parameter> and returns a new array with the + order of the elements reversed, preserving the keys if + <parameter>preserve_keys</parameter> is &true;. + </para> + <para> + <example> + <title><function>array_reverse</function> example</title> + <programlisting role="php"> +<![CDATA[ +$input = array ("php", 4.0, array ("green", "red")); +$result = array_reverse ($input); +$result_keyed = array_reverse ($input, TRUE); +]]> + </programlisting> + <para> + This makes both <varname>$result</varname> and + <varname>$result_keyed</varname> have the same elements, but + note the difference between the keys. The printout of + <varname>$result</varname> and + <varname>$result_keyed</varname> will be: + <screen role="php"> +<![CDATA[ +Array +( + [0] => Array + ( + [0] => green + [1] => red + ) + + [1] => 4 + [2] => php +) +Array +( + [2] => Array + ( + [0] => green + [1] => red + ) + + [1] => 4 + [0] => php +) +]]> + </screen> + </para> + + </example> + </para> + <note> + <para> + The second parameter was added in PHP 4.0.3. + </para> + </note> + </refsect1> + </refentry> + + <refentry id="function.array-reduce"> + <refnamediv> + <refname>array_reduce</refname> + <refpurpose> + Iteratively reduce the array to a single value using a callback + function + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>mixed</type><methodname>array_reduce</methodname> + <methodparam><type>array</type><parameter>input</parameter></methodparam> + <methodparam><type>mixed</type><parameter>callback</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>initial</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_reduce</function> applies iteratively the + <parameter>callback</parameter> function to the elements of the + array <parameter>input</parameter>, so as to reduce the array to + a single value. If the optional <parameter>initial</parameter> is + available, it will be used at the beginning of the process, or as + a final result in case the array is empty. + </para> + <para> + <example> + <title><function>array_reduce</function> example</title> + <programlisting role="php"> +<![CDATA[ +function rsum($v, $w) { + $v += $w; + return $v; +} + +function rmul($v, $w) { + $v *= $w; + return $v; +} + +$a = array(1, 2, 3, 4, 5); +$x = array(); +$b = array_reduce($a, "rsum"); +$c = array_reduce($a, "rmul", 10); +$d = array_reduce($x, "rsum", 1); +]]> + </programlisting> + </example> + </para> + <para> + This will result in <varname>$b</varname> containing + <literal>15</literal>, <varname>$c</varname> containing + <literal>1200</literal> (= 1*2*3*4*5*10), and + <varname>$d</varname> containing <literal>1</literal>. + </para> + <para> + See also <function>array_filter</function> and + <function>array_map</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-shift"> + <refnamediv> + <refname>array_shift</refname> + <refpurpose> + Shift an element off the beginning of array + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>mixed</type><methodname>array_shift</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_shift</function> shifts the first value of the + <parameter>array</parameter> off and returns it, shortening the + <parameter>array</parameter> by one element and moving everything + down. If <parameter>array</parameter> is empty (or is not an + array), &null; will be returned. + </para> + <para> + <example> + <title><function>array_shift</function> example</title> + <programlisting role="php"> +<![CDATA[ +$stack = array ("orange", "banana", "apple", "raspberry"); +$fruit = array_shift ($stack); +]]> + </programlisting> + <para> + This would result in <varname>$stack</varname> having 3 elements left: + <screen role="php"> +<![CDATA[ +Array +( + [0] => banana + [1] => apple + [2] => raspberry +) +]]> + </screen> + and <literal>orange</literal> will be assigned to + <varname>$fruit</varname>. + </para> + </example> + </para> + <para> + See also <function>array_unshift</function>, + <function>array_push</function>, and + <function>array_pop</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-slice"> + <refnamediv> + <refname>array_slice</refname> + <refpurpose>Extract a slice of the array</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_slice</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + <methodparam><type>int</type><parameter>offset</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter> + length + </parameter></methodparam> + </methodsynopsis> + <para> + <function>array_slice</function> returns the sequence of elements + from the array <parameter>array</parameter> as specified by the + <parameter>offset</parameter> and <parameter>length</parameter> + parameters. + </para> + <para> + If <parameter>offset</parameter> is positive, the sequence will + start at that offset in the <parameter>array</parameter>. If + <parameter>offset</parameter> is negative, the sequence will + start that far from the end of the <parameter>array</parameter>. + </para> + <para> + If <parameter>length</parameter> is given and is positive, then + the sequence will have that many elements in it. If + <parameter>length</parameter> is given and is negative then the + sequence will stop that many elements from the end of the + array. If it is omitted, then the sequence will have everything + from <parameter>offset</parameter> up until the end of the + <parameter>array</parameter>. + </para> + <para> + Note that <function>array_slice</function> will ignore array + keys, and will calculate offsets and lengths based on the + actual positions of elements within the array. + </para> + <para> + <example> + <title><function>array_slice</function> examples</title> + <programlisting role="php"> +<![CDATA[ +$input = array ("a", "b", "c", "d", "e"); + +$output = array_slice ($input, 2); // returns "c", "d", and "e" +$output = array_slice ($input, 2, -1); // returns "c", "d" +$output = array_slice ($input, -2, 1); // returns "d" +$output = array_slice ($input, 0, 3); // returns "a", "b", and "c" +]]> + </programlisting> + </example> + </para> + <para> + See also <function>array_splice</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-splice"> + <refnamediv> + <refname>array_splice</refname> + <refpurpose> + Remove a portion of the array and replace it with something + else + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_splice</methodname> + <methodparam><type>array</type><parameter>input</parameter></methodparam> + <methodparam><type>int</type><parameter>offset</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam> + <methodparam choice="opt"><type>array</type><parameter> + replacement + </parameter></methodparam> + </methodsynopsis> + <para> + <function>array_splice</function> removes the elements designated + by <parameter>offset</parameter> and + <parameter>length</parameter> from the + <parameter>input</parameter> array, and replaces them with the + elements of the <parameter>replacement</parameter> array, if + supplied. It returns an array containing the extracted elements. + </para> + <para> + If <parameter>offset</parameter> is positive then the start of + removed portion is at that offset from the beginning of the + <parameter>input</parameter> array. If + <parameter>offset</parameter> is negative then it starts that far + from the end of the <parameter>input</parameter> array. + </para> + <para> + If <parameter>length</parameter> is omitted, removes everything + from <parameter>offset</parameter> to the end of the array. If + <parameter>length</parameter> is specified and is positive, then + that many elements will be removed. If + <parameter>length</parameter> is specified and is negative then + the end of the removed portion will be that many elements from + the end of the array. Tip: to remove everything from + <parameter>offset</parameter> to the end of the array when + <parameter>replacement</parameter> is also specified, use + <literal>count($input)</literal> for + <parameter>length</parameter>. + </para> + <para> + If <parameter>replacement</parameter> array is specified, then + the removed elements are replaced with elements from this array. + If <parameter>offset</parameter> and + <parameter>length</parameter> are such that nothing is removed, + then the elements from the <parameter>replacement</parameter> + array are inserted in the place specified by the + <parameter>offset</parameter>. Tip: if the replacement is just + one element it is not necessary to put <literal>array()</literal> + around it, unless the element is an array itself. + </para> + <para> + The following equivalences hold: + <programlisting role="php"> +<![CDATA[ +array_push ($input, $x, $y) array_splice ($input, count ($input), 0, + array ($x, $y)) +array_pop ($input) array_splice ($input, -1) +array_shift ($input) array_splice ($input, 0, 1) +array_unshift ($input, $x, $y) array_splice ($input, 0, 0, array ($x, $y)) +$a[$x] = $y array_splice ($input, $x, 1, $y) +]]> + </programlisting> + </para> + <para> + Returns the array consisting of removed elements. + </para> + <para> + <example> + <title><function>array_splice</function> examples</title> + <programlisting role="php"> +<![CDATA[ +$input = array ("red", "green", "blue", "yellow"); +array_splice ($input, 2); +// $input is now array ("red", "green") + +$input = array ("red", "green", "blue", "yellow"); +array_splice ($input, 1, -1); +// $input is now array ("red", "yellow") + +$input = array ("red", "green", "blue", "yellow"); +array_splice ($input, 1, count($input), "orange"); +// $input is now array ("red", "orange") + +$input = array ("red", "green", "blue", "yellow"); +array_splice ($input, -1, 1, array("black", "maroon")); +// $input is now array ("red", "green", +// "blue", "black", "maroon") +]]> + </programlisting> + </example> + </para> + <para> + See also <function>array_slice</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-sum"> + <refnamediv> + <refname>array_sum</refname> + <refpurpose> + Calculate the sum of values in an array. + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>mixed</type><methodname>array_sum</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_sum</function> returns the sum of values + in an array as an integer or float. + </para> + <para> + <example> + <title><function>array_sum</function> examples</title> + <programlisting role="php"> +<![CDATA[ +$a = array(2, 4, 6, 8); +echo "sum(a) = ".array_sum($a)."\n"; + +$b = array("a"=>1.2,"b"=>2.3,"c"=>3.4); +echo "sum(b) = ".array_sum($b)."\n"; +]]> + </programlisting> + <para> + The printout of the program above will be: + <screen role="php"> +<![CDATA[ +sum(a) = 20 +sum(b) = 6.9 +]]> + </screen> + </para> + </example> + </para> + <note> + <para> + PHP versions prior to 4.0.6 modified the passed array + itself and converted strings to numbers (which most + of the time converted them to zero, depending on + their value). + </para> + </note> + </refsect1> + </refentry> + + <refentry id="function.array-unique"> + <refnamediv> + <refname>array_unique</refname> + <refpurpose>Removes duplicate values from an array</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_unique</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_unique</function> takes input + <parameter>array</parameter> and returns a new array + without duplicate values. + </para> + <para> + Note that keys are preserved. <function>array_unique</function> sorts + the values treated as string at first, then will keep the first key + encountered for every value, and ignore all following keys. It does not + mean that the key of the first related value from the unsorted + <parameter>array</parameter> will be kept. + </para> + <note> + <simpara> + Two elements are considered equal if and only if + <literal>(string) $elem1 === (string) $elem2</literal>. In words: + when the string representation is the same. + <!-- TODO: example of it... --> + </simpara> + <simpara> + The first element will be used. + </simpara> + </note> + <warning> + <simpara> + This was broken in PHP 4.0.4! + <!-- TODO: when exactly was this broken?... --> + </simpara> + </warning> + <para> + <example> + <title><function>array_unique</function> example</title> + <programlisting role="php"> +<![CDATA[ +$input = array ("a" => "green", "red", "b" => "green", "blue", "red"); +$result = array_unique ($input); +print_r($result); +]]> + </programlisting> + <para> + This will output: + <screen role="php"> +<![CDATA[ +Array +( + [b] => green + [1] => blue + [2] => red +) +]]> + </screen> + </para> + </example> + </para> + <para> + <example> + <title><function>array_unique</function> and types</title> + <programlisting role="php"> +<![CDATA[ +$input = array (4,"4","3",4,3,"3"); +$result = array_unique ($input); +var_dump($result); +]]> + </programlisting> + <para> + The printout of the program above will be (PHP 4.0.6): + <screen role="php"> +<![CDATA[ +array(2) { + [3]=> + int(4) + [4]=> + int(3) +} +]]> + </screen> + </para> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.array-unshift"> + <refnamediv> + <refname>array_unshift</refname> + <refpurpose> + Prepend one or more elements to the beginning of array + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>int</type><methodname>array_unshift</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + <methodparam><type>mixed</type><parameter>var</parameter></methodparam> + <methodparam choice="opt"><type>mixed</type><parameter> + ... + </parameter></methodparam> + </methodsynopsis> + <para> + <function>array_unshift</function> prepends passed elements to + the front of the <parameter>array</parameter>. Note that the list + of elements is prepended as a whole, so that the prepended + elements stay in the same order. + </para> + <para> + Returns the new number of elements in the + <parameter>array</parameter>. + </para> + <para> + <example> + <title><function>array_unshift</function> example</title> + <programlisting role="php"> +<![CDATA[ +$queue = array ("orange", "banana"); +array_unshift ($queue, "apple", "raspberry"); +]]> + </programlisting> + <para> + This would result in <varname>$queue</varname> having the + following elements: + <screen role="php"> +<![CDATA[ +Array +( + [0] => apple + [1] => raspberry + [2] => orange + [3] => banana +) +]]> + </screen> + </para> + </example> + </para> + <para> + See also <function>array_shift</function>, + <function>array_push</function>, and + <function>array_pop</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-values"> + <refnamediv> + <refname>array_values</refname> + <refpurpose>Return all the values of an array</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>array_values</methodname> + <methodparam><type>array</type><parameter>input</parameter></methodparam> + </methodsynopsis> + <para> + <function>array_values</function> returns all the values from the + <parameter>input</parameter> array. + </para> + <para> + <example> + <title><function>array_values</function> example</title> + <programlisting role="php"> +<![CDATA[ +$array = array ("size" => "XL", "color" => "gold"); +print_r(array_values ($array)); +]]> + </programlisting> + <para> + This will output: + <screen role="php"> +<![CDATA[ +Array +( + [0] => XL + [1] => gold +) +]]> + </screen> + </para> + </example> + </para> + <note> + <para> + This function was added to PHP 4, below is an implementation for + those still using PHP 3. + <example> + <title> + Implementation of <function>array_values</function> for PHP 3 + users + </title> + <programlisting role="php"> +<![CDATA[ +function array_values ($arr) { + $t = array(); + while (list($k, $v) = each ($arr)) { + $t[] = $v; + } + return $t; +} +]]> + </programlisting> + </example> + </para> + </note> + <para> + See also <function>array_keys</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-walk"> + <refnamediv> + <refname>array_walk</refname> + <refpurpose> + Apply a user function to every member of an array + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>int</type><methodname>array_walk</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + <methodparam><type>string</type><parameter>func</parameter></methodparam> + <methodparam choice="opt"><type>mixed</type><parameter>userdata</parameter></methodparam> + </methodsynopsis> + <simpara> + Applies the user-defined function named by <parameter>func</parameter> + to each element of <parameter>array</parameter>. + <parameter>func</parameter> will be passed array value as the + first parameter and array key as the second parameter. If + <parameter>userdata</parameter> is supplied, it will be passed as + the third parameter to the user function. <parameter>func</parameter> + must be a user-defined function, and can't be a native PHP function. + Thus, you can't use <function>array_walk</function> straight with + <function>str2lower</function>, you must build a user-defined function + with it first, and pass this function as argument. + </simpara> + &note.func-callback; + <simpara> + If <parameter>func</parameter> requires more than two or three + arguments, depending on <parameter>userdata</parameter>, 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>. + </simpara> + <note> + <para> + If <parameter>func</parameter> needs to be working with the + actual values of the array, specify that the first parameter of + <parameter>func</parameter> should be passed by reference. Then + any changes made to those elements will be made in the array + itself. + </para> + <para> + Modifying the array from inside <parameter>func</parameter> + may cause unpredictable behavior. + </para> + </note> + <note> + <para> + Passing the key and userdata to <parameter>func</parameter> was + added in 4.0. + </para> + <para> + In PHP 4 <function>reset</function> needs to be called as + necessary since <function>array_walk</function> does not reset + the array by default. + </para> + <para> + Users may not change the array itself from the callback + function. e.g. Add/delete element, unset the array that + <function>array_walk</function> is applied to. If the array is + changed, the behavior of this function is undefined. + </para> + </note> + <para> + <example> + <title><function>array_walk</function> example</title> + <programlisting role="php"> +<![CDATA[ +$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple"); + +function test_alter (&$item1, $key, $prefix) { + $item1 = "$prefix: $item1"; +} + +function test_print ($item2, $key) { + echo "$key. $item2<br>\n"; +} +echo "Before ...:\n"; +array_walk ($fruits, 'test_print'); +reset ($fruits); +array_walk ($fruits, 'test_alter', 'fruit'); +echo "... and after:\n"; +reset ($fruits); +array_walk ($fruits, 'test_print'); +]]> + </programlisting> + <para> + The printout of the program above will be: + <screen role="php"> +<![CDATA[ +Before ...: +d. lemon +a. orange +b. banana +c. apple +... and after: +d. fruit: lemon +a. fruit: orange +b. fruit: banana +c. fruit: apple +]]> + </screen> + </para> + </example> + </para> + <simpara> + See also <function>each</function> and <function>list</function>. + </simpara> + </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>Beschrijving</title> + <methodsynopsis> + <type>void</type><methodname>arsort</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>sort_flags</parameter></methodparam> + </methodsynopsis> + <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. + </para> + <example> + <title><function>arsort</function> example</title> + <programlisting role="php"> +<![CDATA[ +$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple"); +arsort ($fruits); +reset ($fruits); +while (list ($key, $val) = each ($fruits)) { + echo "$key = $val\n"; +} +]]> + </programlisting> + <para> + This example would display: + <screen> +<![CDATA[ +a = orange +d = lemon +b = banana +c = apple +]]> + </screen> + </para> + </example> + <para> + The fruits have been sorted in reverse alphabetical order, and + the index associated with each element has been maintained. + </para> + <para> + You may modify the behavior of the sort using the optional + parameter <parameter>sort_flags</parameter>, for details + see <function>sort</function>. + </para> + <para> + See also <function>asort</function>, <function>rsort</function>, + <function>ksort</function>, and <function>sort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.asort"> + <refnamediv> + <refname>asort</refname> + <refpurpose>Sort an array and maintain index association</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>void</type><methodname>asort</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>sort_flags</parameter></methodparam> + </methodsynopsis> + <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. + </para> + <example> + <title><function>asort</function> example</title> + <programlisting role="php"> +<![CDATA[ +$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple"); +asort ($fruits); +reset ($fruits); +while (list ($key, $val) = each ($fruits)) { + echo "$key = $val\n"; +} +]]> + </programlisting> + <para> + This example would display: + <screen> +<![CDATA[ +c = apple +b = banana +d = lemon +a = orange +]]> + </screen> + </para> + </example> + <para> + The fruits have been sorted in alphabetical order, and the index + associated with each element has been maintained. + </para> + <para> + You may modify the behavior of the sort using the optional + parameter <parameter>sort_flags</parameter>, for details + see <function>sort</function>. + </para> + <para> + See also <function>arsort</function>, <function>rsort</function>, + <function>ksort</function>, and <function>sort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.compact"> + <refnamediv> + <refname>compact</refname> + <refpurpose> + Create array containing variables and their values + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>compact</methodname> + <methodparam><type>mixed</type><parameter>varname</parameter></methodparam> + <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam> + </methodsynopsis> + <para> + <function>compact</function> takes a variable number of + parameters. Each parameter can be either a string containing the + name of the variable, or an array of variable names. The array + can contain other arrays of variable names inside it; + <function>compact</function> handles it recursively. + </para> + <para> + For each of these, <function>compact</function> looks for a + variable with that name in the current symbol table and adds it + to the output array such that the variable name becomes the key + and the contents of the variable become the value for that key. + In short, it does the opposite of <function>extract</function>. + It returns the output array with all the variables added to it. + </para> + <para> + Any strings that are not set will simply be skipped. + </para> + <para> + <example> + <title><function>compact</function> example</title> + <programlisting role="php"> +<![CDATA[ +$city = "San Francisco"; +$state = "CA"; +$event = "SIGGRAPH"; + +$location_vars = array ("city", "state"); + +$result = compact ("event", "nothing_here", $location_vars); +]]> + </programlisting> + <para> + After this, <varname>$result</varname> will be: + <screen role="php"> +<![CDATA[ +Array +( + [event] => SIGGRAPH + [city] => San Francisco + [state] => CA +) +]]> + </screen> + </para> + </example> + </para> + <para> + See also <function>extract</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.count"> + <refnamediv> + <refname>count</refname> + <refpurpose>Count elements in a variable</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>int</type><methodname>count</methodname> + <methodparam><type>mixed</type><parameter>var</parameter></methodparam> + </methodsynopsis> + <para> + Returns the number of elements in <parameter>var</parameter>, + which is typically an <type>array</type> (since anything else will have + one element). + </para> + <para> + If <parameter>var</parameter> is not an array, <literal>1</literal> will + be returned (exception: <literal>count(&null;)</literal> equals + <literal>0</literal>). + </para> + <warning> + <para> + <function>count</function> may return 0 for a variable that + isn't set, but it may also return 0 for a variable that has + been initialized with an empty array. Use + <function>isset</function> to test if a variable is set. + </para> + </warning> + <para> + Please see the <link linkend="language.types.array">Arrays</link> + section of the manual for a detailed explanation of how arrays + are implemented and used in PHP. + </para> + <para> + <example> + <title><function>count</function> example</title> + <programlisting role="php"> + <!-- TODO: examples about count(null), count(false), count(object).. --> +<![CDATA[ +$a[0] = 1; +$a[1] = 3; +$a[2] = 5; +$result = count ($a); +// $result == 3 + +$b[0] = 7; +$b[5] = 9; +$b[10] = 11; +$result = count ($b); +// $result == 3; +]]> + </programlisting> + </example> + </para> + <note> + <para> + The <function>sizeof</function> function is an + <link linkend="aliases">alias</link> for <function>count</function>. + </para> + </note> + <para> + See also <function>is_array</function>, + <function>isset</function>, and + <function>strlen</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.current"> + <refnamediv> + <refname>current</refname> + <refpurpose>Return the current element in an array</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>mixed</type><methodname>current</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + </methodsynopsis> + <para> + Every array has an internal pointer to its "current" element, + which is initialized to the first element inserted into the + array. + </para> + <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;. + <warning> + <para> + If the array contains empty elements (0 or "", the empty + string) then this function will return &false; + for these elements as well. This makes it impossible to + determine if you are really at the end of the list in such + an array using <function>current</function>. To properly + traverse an array that may contain empty elements, use the + <function>each</function> function. + </para> + </warning> + </para> + <para> + See also <function>end</function>, <function>next</function>, + <function>prev</function>, and <function>reset</function>. + </para> + </refsect1> + </refentry> + + <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>Beschrijving</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>$HTTP_POST_VARS</varname>: + <example> + <title> + Traversing <varname>$HTTP_POST_VARS</varname> with + <function>each</function> + </title> + <programlisting role="php"> +<![CDATA[ +echo "Values submitted via POST method:<br>"; +reset ($HTTP_POST_VARS); +while (list ($key, $val) = each ($HTTP_POST_VARS)) { + echo "$key => $val<br>"; +} +]]> + </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>, and <function>prev</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.end"> + <refnamediv> + <refname>end</refname> + <refpurpose> + Set the internal pointer of an array to its last element + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>mixed</type><methodname>end</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + </methodsynopsis> + <para> + <function>end</function> advances <parameter>array</parameter>'s + internal pointer to the last element, and returns that element. + </para> + <para> + See also <function>current</function>, + <function>each</function>, + <function>next</function>, and <function>reset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.extract"> + <refnamediv> + <refname>extract</refname> + <refpurpose> + Import variables into the current symbol table from an array + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>int</type><methodname>extract</methodname> + <methodparam><type>array</type><parameter>var_array</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>extract_type</parameter></methodparam> + <methodparam choice="opt"><type>string</type><parameter>prefix</parameter></methodparam> + </methodsynopsis> + <para> + This function is used to import variables from an array into the + current symbol table. It takes an associative array + <parameter>var_array</parameter> and treats keys as variable + names and values as variable values. For each key/value pair it + will create a variable in the current symbol table, subject to + <parameter>extract_type</parameter> and + <parameter>prefix</parameter> parameters. + </para> + <note> + <para> + Since version 4.0.5 this function returns the number of + variables extracted. + </para> + </note> + <note> + <para> + EXTR_IF_EXISTS and EXTR_PREFIX_IF_EXISTS was introduced in version 4.2.0. + </para> + </note> + <para> + <function>extract</function> checks each key to see whether it + constitutes a valid variable name and also for collisions with + existing variables in the symbol table. The way invalid/numeric + keys and collisions are treated is determined by + <parameter>extract_type</parameter>. It can be one of the + following values: + <variablelist> + <varlistentry> + <term>EXTR_OVERWRITE</term> + <listitem> + <simpara> + If there is a collision, overwrite the existing variable. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_SKIP</term> + <listitem> + <simpara> + If there is a collision, don't overwrite the existing + variable. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_PREFIX_SAME</term> + <listitem> + <simpara>If there is a collision, prefix the variable name with + <parameter>prefix</parameter>. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_PREFIX_ALL</term> + <listitem> + <simpara> + Prefix all variable names with + <parameter>prefix</parameter>. Since PHP 4.0.5 this includes + numeric ones as well. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_PREFIX_INVALID</term> + <listitem> + <simpara> + Only prefix invalid/numeric variable names with + <parameter>prefix</parameter>. This flag was added in + PHP 4.0.5. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_IF_EXISTS</term> + <listitem> + <simpara> + Only overwrite the variable if it already exists in the + current symbol table, otherwise do nothing. This is useful + for defining a list of valid variables and then extracting + only those variables you have defined out of $_REQUEST, for + example. This flag was added in PHP 4.2.0. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_PREFIX_IF_EXISTS</term> + <listitem> + <simpara> + Only create prefixed variable names if the non-prefixed version + of the same variable exists in the current symbol table. This + flag was added in PHP 4.2.0. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + If <parameter>extract_type</parameter> is not specified, it is + assumed to be EXTR_OVERWRITE. + </para> + <para> + Note that <parameter>prefix</parameter> is only required if + <parameter>extract_type</parameter> is EXTR_PREFIX_SAME, + EXTR_PREFIX_ALL, EXTR_PREFIX_INVALID or EXTR_PREFIX_IF_EXISTS. If + the prefixed result is not a valid variable name, it is not + imported into the symbol table. + </para> + <para> + <function>extract</function> returns the number of variables + successfully imported into the symbol table. + </para> + <para> + A possible use for extract is to import into the symbol table + variables contained in an associative array returned by + <function>wddx_deserialize</function>. + </para> + <para> + <example> + <title><function>extract</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +/* Suppose that $var_array is an array returned from + wddx_deserialize */ + +$size = "large"; +$var_array = array ("color" => "blue", + "size" => "medium", + "shape" => "sphere"); +extract ($var_array, EXTR_PREFIX_SAME, "wddx"); + +print "$color, $size, $shape, $wddx_size\n"; + +?> +]]> + </programlisting> + </example> + </para> + <para> + The above example will produce: + <programlisting> +<![CDATA[ +blue, large, sphere, medium +]]> + </programlisting> + </para> + <para> + The <varname>$size</varname> wasn't overwritten, because we + specified EXTR_PREFIX_SAME, which resulted in + <varname>$wddx_size</varname> being created. If EXTR_SKIP was + specified, then $wddx_size wouldn't even have been created. + EXTR_OVERWRITE would have caused <varname>$size</varname> to have + value "medium", and EXTR_PREFIX_ALL would result in new variables + being named <varname>$wddx_color</varname>, + <varname>$wddx_size</varname>, and + <varname>$wddx_shape</varname>. + </para> + <para> + You must use an associative array, a numerically indexed array + will not produce results unless you use EXTR_PREFIX_ALL or + EXTR_PREFIX_INVALID. + </para> + <para> + See also <function>compact</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.in-array"> + <refnamediv> + <refname>in_array</refname> + <refpurpose>Return &true; if a value exists in an array</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>bool</type><methodname>in_array</methodname> + <methodparam><type>mixed</type><parameter>needle</parameter></methodparam> + <methodparam><type>array</type><parameter>haystack</parameter></methodparam> + <methodparam choice="opt"><type>bool</type><parameter>strict</parameter></methodparam> + </methodsynopsis> + <para> + Searches <parameter>haystack</parameter> for + <parameter>needle</parameter> and returns &true; + if it is found in the array, &false; otherwise. + </para> + <para> + If the third parameter <parameter>strict</parameter> is set to + &true; then the <function>in_array</function> function + will also check the <link linkend="language.types">types</link> of + the <parameter>needle</parameter> in the <parameter>haystack</parameter>. + </para> + <note> + <para> + If <parameter>needle</parameter> is a string, the comparison is done in + a case-sensitive manner. + </para> + </note> + <note> + <para> + In PHP versions before 4.2.0 <parameter>needle</parameter> was not + allowed to be an array. + </para> + </note> + <para> + <example> + <title><function>in_array</function> example</title> + <programlisting role="php"> +<![CDATA[ +$os = array ("Mac", "NT", "Irix", "Linux"); +if (in_array ("Irix", $os)) { + print "Got Irix"; +} +if (in_array ("mac", $os)) { + print "Got mac"; +} +]]> + </programlisting> + <para> + The second condition fails because <function>in_array</function> + is case-sensitive, so the program above will display: + <screen role="php"> +<![CDATA[ +Got Irix +]]> + </screen> + </para> + </example> + </para> + <para> + <example> + <title><function>in_array</function> with strict example</title> + <programlisting role="php"> +<![CDATA[ +<?php +$a = array('1.10', 12.4, 1.13); + +if (in_array('12.4', $a, TRUE)) + echo "'12.4' found with strict check\n"; +if (in_array(1.13, $a, TRUE)) + echo "1.13 found with strict check\n"; +?> +]]> + </programlisting> + <para> + This will display: + <screen role="php"> +<![CDATA[ +1.13 found with strict check +]]> + </screen> + </para> + </example> + </para> + <para> + <example> + <title><function>in_array</function> with an array as needle</title> + <programlisting role="php"> +<![CDATA[ +<?php +$a = array(array('p', 'h'), array('p', 'r'), 'o'); + +if (in_array(array ('p', 'h'), $a)) + echo "'ph' is found\n"; +if (in_array(array ('f', 'i'), $a)) + echo "'fi' is not found\n"; +if (in_array('o', $a)) + echo "'o' is found\n"; +?> + +// This will output: + +'ph' is found +'o' is found +]]> + </programlisting> + </example> + </para> + <para> + See also <function>array_search</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.array-search"> + <refnamediv> + <refname>array_search</refname> + <refpurpose> + Searches the array for a given value and returns the + corresponding key if successful + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>mixed</type><methodname>array_search</methodname> + <methodparam><type>mixed</type><parameter>needle</parameter></methodparam> + <methodparam><type>array</type><parameter>haystack</parameter></methodparam> + <methodparam choice="opt"><type>bool</type><parameter>strict</parameter></methodparam> + </methodsynopsis> + <para> + Searches <parameter>haystack</parameter> for + <parameter>needle</parameter> and returns the key if it is found in + the array, &false; otherwise. + </para> + <note> + <para> + Prior to PHP 4.2.0, <function>array_search</function> returns + <constant>NULL</constant> on failure instead of &false;. + </para> + </note> + <para> + If the optional third parameter <parameter>strict</parameter> is set to + &true; then the <function>array_search</function> + will also check the types of the <parameter>needle</parameter> + in the <parameter>haystack</parameter>. + </para> + &return.falseproblem; + <para> + See also <function>array_keys</function> and <function>in_array</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.key"> + <refnamediv> + <refname>key</refname> + <refpurpose>Fetch a key from an associative array</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>mixed</type><methodname>key</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + </methodsynopsis> + <para> + <function>key</function> returns the index element of the + current array position. + </para> + <para> + See also <function>current</function> and <function>next</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.krsort"> + <refnamediv> + <refname>krsort</refname> + <refpurpose>Sort an array by key in reverse order</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>int</type><methodname>krsort</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>sort_flags</parameter></methodparam> + </methodsynopsis> + <para> + Sorts an array by key in reverse order, maintaining key to data + correlations. This is useful mainly for associative arrays. + <example> + <title><function>krsort</function> example</title> + <programlisting role="php"> +<![CDATA[ +$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple"); +krsort ($fruits); +reset ($fruits); +while (list ($key, $val) = each ($fruits)) { + echo "$key = $val\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + This example would display: + </para> + <para> + <screen> +<![CDATA[ +d = lemon +c = apple +b = banana +a = orange +]]> + </screen> + </para> + <para> + You may modify the behavior of the sort using the optional + parameter <parameter>sort_flags</parameter>, for details + see <function>sort</function>. + </para> + <simpara> + See also <function>asort</function>, <function>arsort</function>, + <function>ksort</function>, <function>sort</function>, + <function>natsort</function>, and <function>rsort</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.ksort"> + <refnamediv> + <refname>ksort</refname> + <refpurpose>Sort an array by key</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>int</type><methodname>ksort</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>sort_flags</parameter></methodparam> + </methodsynopsis> + <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 role="php"> +<![CDATA[ +$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple"); +ksort ($fruits); +reset ($fruits); +while (list ($key, $val) = each ($fruits)) { + echo "$key = $val\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + This example would display: + </para> + <para> + <screen> +<![CDATA[ +a = orange +b = banana +c = apple +d = lemon +]]> + </screen> + </para> + <para> + You may modify the behavior of the sort using the optional + parameter <parameter>sort_flags</parameter>, for details + see <function>sort</function>. + </para> + <simpara> + See also <function>asort</function>, <function>arsort</function>, + <function>krsort</function>, <function>uksort</function>, + <function>sort</function>, <function>natsort</function>, and + <function>rsort</function>. + </simpara> + <note> + <para> + The second parameter was added in PHP 4. + </para> + </note> + </refsect1> + </refentry> + + <refentry id="function.list"> + <refnamediv> + <refname>list</refname> + <refpurpose> + Assign variables as if they were an array + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>void</type><methodname>list</methodname> + <methodparam rep="repeat"><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> + <note> + <para> + <function>list</function> only works on numerical arrays and assumes + the numerical indices start at 0. + </para> + </note> + <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; +print "$drink is $color and $power makes it special.\n"; + +// Listing some of them +list($drink, , $power) = $info; +print "$drink has $power.\n"; + +// Or let's skip to only the third one +list( , , $power) = $info; +print "I need $power!\n"; + +?> +]]> + </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 = mysql_query ("SELECT id, name, salary FROM employees",$conn); +while (list ($id, $name, $salary) = mysql_fetch_row ($result)) { + print (" <tr>\n". + " <td><a href=\"info.php?id=$id\">$name</a></td>\n". + " <td>$salary</td>\n". + " </tr>\n"); +} + +?> + +</table> +]]> + </programlisting> + </example> + </para> + <para> + See also <function>each</function>, <function>array</function> + and <function>extract</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.natsort"> + <refnamediv> + <refname>natsort</refname> + <refpurpose> + Sort an array using a "natural order" algorithm + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>void</type><methodname>natsort</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + </methodsynopsis> + <para> + This function implements a sort algorithm that orders + alphanumeric strings in the way a human being would. This is + described as a "natural ordering". An example of the difference + between this algorithm and the regular computer string sorting + algorithms (used in <function>sort</function>) can be seen below: + </para> + <para> + <example> + <title><function>natsort</function> example</title> + <programlisting role="php"> +<![CDATA[ +$array1 = $array2 = array ("img12.png", "img10.png", "img2.png", "img1.png"); + +sort($array1); +echo "Standard sorting\n"; +print_r($array1); + +natsort($array2); +echo "\nNatural order sorting\n"; +print_r($array2); +]]> + </programlisting> + </example> + </para> + <para> + The code above will generate the following output: + </para> + <para> + <screen> +<![CDATA[ +Standard sorting +Array +( + [0] => img1.png + [1] => img10.png + [2] => img12.png + [3] => img2.png +) + +Natural order sorting +Array +( + [3] => img1.png + [2] => img2.png + [1] => img10.png + [0] => img12.png +) +]]> + </screen> + For more information see: Martin Pool's <ulink + url="&url.strnatcmp;">Natural Order String Comparison</ulink> + page. + </para> + <para> + See also <function>natcasesort</function>, + <function>strnatcmp</function>, and + <function>strnatcasecmp</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.natcasesort"> + <refnamediv> + <refname>natcasesort</refname> + <refpurpose> + Sort an array using a case insensitive "natural order" algorithm + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>void</type><methodname>natcasesort</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + </methodsynopsis> + <para> + This function implements a sort algorithm that orders + alphanumeric strings in the way a human being would. This is + described as a "natural ordering". + </para> + <para> + <function>natcasesort</function> is a case insensitive version of + <function>natsort</function>. See <function>natsort</function> + for an example of the difference between this algorithm and the + regular computer string sorting algorithms. + </para> + <para> + For more information see: Martin Pool's <ulink + url="&url.strnatcmp;">Natural Order String Comparison</ulink> + page. + </para> + <para> + See also <function>sort</function>, + <function>natsort</function>, + <function>strnatcmp</function>, and + <function>strnatcasecmp</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.next"> + <refnamediv> + <refname>next</refname> + <refpurpose> + Advance the internal array pointer of an array + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>mixed</type><methodname>next</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + </methodsynopsis> + <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. + </para> + <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;. + <warning> + <para> + If the array contains empty elements, or elements that have a key + value of 0 then this function will return &false; + for these elements as well. To properly traverse an array which + may contain empty elements or elements with key values of 0 see the + <function>each</function> function. + </para> + </warning> + </para> + <para> + See also + <function>current</function>, <function>end</function>, + <function>prev</function>, and <function>reset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.pos"> + <refnamediv> + <refname>pos</refname> + <refpurpose>Get the current element from an array</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>mixed</type><methodname>pos</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + </methodsynopsis> + <simpara> + This is an <link linkend="aliases">alias</link> + for <function>current</function>. + </simpara> + <para> + See also + <function>end</function>, <function>next</function>, + <function>prev</function>, and <function>reset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.prev"> + <refnamediv> + <refname>prev</refname> + <refpurpose>Rewind the internal array pointer</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>mixed</type><methodname>prev</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + </methodsynopsis> + <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. + <warning> + <para> + 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> + </warning> + </para> + <para> + <function>prev</function> behaves just like + <function>next</function>, except it rewinds the internal array + pointer one place instead of advancing it. + </para> + <para> + See also <function>current</function>, <function>end</function>, + <function>next</function>, and <function>reset</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.range"> + <refnamediv> + <refname>range</refname> + <refpurpose> + Create an array containing a range of elements + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>array</type><methodname>range</methodname> + <methodparam><type>mixed</type><parameter>low</parameter></methodparam> + <methodparam><type>mixed</type><parameter>high</parameter></methodparam> + </methodsynopsis> + <para> + <function>range</function> returns an array of elements from + <parameter>low</parameter> to <parameter>high</parameter>, + inclusive. If low > high, the sequence will be from high to low. + </para> + <example> + <title><function>range</function> examples</title> + <programlisting role="php"> +<![CDATA[ +foreach(range(0, 9) as $number) { + echo $number; +} +foreach(range('a', 'z') as $letter) { + echo $letter; +} +foreach(range('z', 'a') as $letter) { + echo $letter; +} +]]> + </programlisting> + </example> + <note> + <para> + Prior to version 4.1.0 the <function>range</function> function + only generated incrementing integer arrays. Support for + character sequences and decrementing arrays was added in 4.1.0. + </para> + <example> + <title>Simulating decrementing ranges and character sequences</title> + <programlisting role="php"> +<![CDATA[ +# array_reverse can be used to flip the order of a range +foreach(array_reverse(range(0,9)) as $number) { + echo $number; +} + +# array_map() can be used to turn integers into characters using chr() +foreach(array_map('chr', range(ord('a'),ord('z'))) as $character) { + echo $character; +} +]]> + </programlisting> + </example> + </note> + <para> + See <function>shuffle</function> for another example of its use. + </para> + </refsect1> + </refentry> + + <refentry id="function.reset"> + <refnamediv> + <refname>reset</refname> + <refpurpose> + Set the internal pointer of an array to its first element + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>mixed</type><methodname>reset</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + </methodsynopsis> + <para> + <function>reset</function> rewinds <parameter>array</parameter>'s + internal pointer to the first element. + </para> + <para> + <function>reset</function> returns the value of the first array + element. + </para> + <para> + See also <function>current</function>, + <function>each</function>, <function>next</function>, + and <function>prev</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.rsort"> + <refnamediv> + <refname>rsort</refname> + <refpurpose>Sort an array in reverse order</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>void</type><methodname>rsort</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>sort_flags</parameter></methodparam> + </methodsynopsis> + <para> + This function sorts an array in reverse order (highest to lowest). + <example> + <title><function>rsort</function> example</title> + <programlisting role="php"> +<![CDATA[ +$fruits = array ("lemon", "orange", "banana", "apple"); +rsort ($fruits); +reset ($fruits); +while (list ($key, $val) = each ($fruits)) { + echo "$key = $val\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + This example would display: + </para> + <para> + <screen> +<![CDATA[ +0 = orange +1 = lemon +2 = banana +3 = apple +]]> + </screen> + </para> + <para> + The fruits have been sorted in reverse alphabetical order. + </para> + <para> + You may modify the behavior of the sort using the optional + parameter <parameter>sort_flags</parameter>, for details + see <function>sort</function>. + </para> + <para> + See also <function>arsort</function>, + <function>asort</function>, <function>ksort</function>, + <function>sort</function>, and <function>usort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.shuffle"> + <refnamediv> + <refname>shuffle</refname> + <refpurpose>Shuffle an array</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>void</type><methodname>shuffle</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + </methodsynopsis> + <para> + This function shuffles (randomizes the order of the elements in) + an array. You must use <function>srand</function> to seed this + function. + <example> + <title><function>shuffle</function> example</title> + <programlisting role="php"> +<![CDATA[ +$numbers = range (1,20); +srand ((float)microtime()*1000000); +shuffle ($numbers); +while (list (, $number) = each ($numbers)) { + echo "$number "; +} +]]> + </programlisting> + </example> + </para> + <para> + See also <function>arsort</function>, <function>asort</function>, + <function>ksort</function>, <function>rsort</function>, + <function>sort</function>, and <function>usort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.sizeof"> + <refnamediv> + <refname>sizeof</refname> + <refpurpose>Get the number of elements in variable</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>int</type><methodname>sizeof</methodname> + <methodparam><type>mixed</type><parameter>var</parameter></methodparam> + </methodsynopsis> + <para> + The <function>sizeof</function> function is an + <link linkend="aliases">alias</link> for <function>count</function>. + </para> + <para> + See also <function>count</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.sort"> + <refnamediv> + <refname>sort</refname> + <refpurpose>Sort an array</refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>void</type><methodname>sort</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>sort_flags</parameter></methodparam> + </methodsynopsis> + <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 role="php"> +<![CDATA[ +<?php + +$fruits = array ("lemon", "orange", "banana", "apple"); +sort ($fruits); +reset ($fruits); +while (list ($key, $val) = each ($fruits)) { + echo "fruits[".$key."] = ".$val."\n"; +} + +?> +]]> + </programlisting> + </example> + </para> + <para> + This example would display: + </para> + <para> + <screen> +<![CDATA[ +fruits[0] = apple +fruits[1] = banana +fruits[2] = lemon +fruits[3] = orange +]]> + </screen> + </para> + <para> + The fruits have been sorted in alphabetical order. + </para> + <para> + The optional second parameter <parameter>sort_flags</parameter> + may be used to modify the sorting behavior using these values: + </para> + <para> + Sorting type flags: + <itemizedlist> + <listitem> + <simpara>SORT_REGULAR - compare items normally</simpara> + </listitem> + <listitem> + <simpara>SORT_NUMERIC - compare items numerically</simpara> + </listitem> + <listitem> + <simpara>SORT_STRING - compare items as strings</simpara> + </listitem> + </itemizedlist> + </para> + <para> + See also <function>arsort</function>, + <function>asort</function>, <function>ksort</function>, + <function>natsort</function>, <function>natcasesort</function>, + <function>rsort</function>, <function>usort</function>, + <function>array_multisort</function>, and + <function>uksort</function>. + </para> + <note> + <para> + The second parameter was added in PHP 4. + </para> + </note> + </refsect1> + </refentry> + + <refentry id="function.uasort"> + <refnamediv> + <refname>uasort</refname> + <refpurpose> + Sort an array with a user-defined comparison function and + maintain index association + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>void</type><methodname>uasort</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + <methodparam><type>function</type><parameter>cmp_function</parameter></methodparam> + </methodsynopsis> + <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. The comparison function + is user-defined. + </para> + <note> + <para> + Please see <function>usort</function> and + <function>uksort</function> for examples of user-defined + comparison functions. + </para> + </note> + &note.func-callback; + <para> + See also <function>usort</function>, <function>uksort</function>, + <function>sort</function>, <function>asort</function>, + <function>arsort</function>, <function>ksort</function>, + and <function>rsort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.uksort"> + <refnamediv> + <refname>uksort</refname> + <refpurpose> + Sort an array by keys using a user-defined comparison function + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>void</type><methodname>uksort</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + <methodparam><type>function</type><parameter>cmp_function</parameter></methodparam> + </methodsynopsis> + <para> + This function will sort the keys of 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. + </para> + <example> + <title><function>uksort</function> example</title> + <programlisting role="php"> +<![CDATA[ +function cmp ($a, $b) { + if ($a == $b) return 0; + return ($a > $b) ? -1 : 1; +} + +$a = array (4 => "four", 3 => "three", 20 => "twenty", 10 => "ten"); + +uksort ($a, "cmp"); + +while (list ($key, $value) = each ($a)) { + echo "$key: $value\n"; +} +]]> + </programlisting> + </example> + <para> + This example would display: + </para> + <para> + <screen> +<![CDATA[ +20: twenty +10: ten +4: four +3: three +]]> + </screen> + </para> + &note.func-callback; + <para> + See also <function>usort</function>, <function>uasort</function>, + <function>sort</function>, <function>asort</function>, + <function>arsort</function>, <function>ksort</function>, + <function>natsort</function>, and <function>rsort</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.usort"> + <refnamediv> + <refname>usort</refname> + <refpurpose> + Sort an array by values using a user-defined comparison function + </refpurpose> + </refnamediv> + <refsect1> + <title>Beschrijving</title> + <methodsynopsis> + <type>void</type><methodname>usort</methodname> + <methodparam><type>array</type><parameter>array</parameter></methodparam> + <methodparam><type>string</type><parameter>cmp_function</parameter></methodparam> + </methodsynopsis> + <para> + This function will sort an array by its values 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. + </para> + <para> + The comparison function must return an integer less than, equal + to, or greater than zero if the first argument is considered to + be respectively less than, equal to, or greater than the + second. If two members compare as equal, their order in the + sorted array is undefined. + </para> + <para> + <example> + <title><function>usort</function> example</title> + <programlisting role="php"> +<![CDATA[ +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> + </para> + <para> + This example would display: + </para> + <para> + <screen> +<![CDATA[ +0: 6 +1: 5 +2: 3 +3: 2 +4: 1 +]]> + </screen> + </para> + <note> + <para> + Obviously in this trivial case the <function>rsort</function> + function would be more appropriate. + </para> + </note> + <para> + <example> + <title> + <function>usort</function> example using multi-dimensional array + </title> + <programlisting role="php"> +<![CDATA[ +function cmp ($a, $b) { + return strcmp($a["fruit"], $b["fruit"]); +} + +$fruits[0]["fruit"] = "lemons"; +$fruits[1]["fruit"] = "apples"; +$fruits[2]["fruit"] = "grapes"; + +usort($fruits, "cmp"); + +while (list ($key, $value) = each ($fruits)) { + echo "\$fruits[$key]: " . $value["fruit"] . "\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + When sorting a multi-dimensional array, $a and $b contain + references to the first index of the array. + </para> + <para> + This example would display: + </para> + <para> + <screen> +<![CDATA[ +$fruits[0]: apples +$fruits[1]: grapes +$fruits[2]: lemons +]]> + </screen> + </para> + &note.func-callback; + <para> + <example> + <title> + <function>usort</function> example using a member function of an object + </title> + <programlisting role="php"> +<![CDATA[ +class TestObj { + var $name; + + function TestObj($name) + { + $this->name = $name; + } + + /* This is the static comparing function: */ + function cmp_obj($a, $b) + { + $al = strtolower($a->name); + $bl = strtolower($b->name); + if ($al == $bl) return 0; + return ($al > $bl) ? +1 : -1; + } +} + +$a[] = new TestObj("c"); +$a[] = new TestObj("b"); +$a[] = new TestObj("d"); + +uasort($a, array ("TestObj", "cmp_obj")); + +foreach ($a as $item) { + print $item->name."\n"; +} +]]> + </programlisting> + </example> + </para> + <para> + This example would display: + </para> + <para> + <screen> +b +c +d + </screen> + </para> + <warning> + <para> + The underlying quicksort function in some C libraries (such as + on Solaris systems) may cause PHP to crash if the comparison + function does not return consistent values. + </para> + </warning> + <para> + See also <function>uasort</function>, + <function>uksort</function>, <function>sort</function>, + <function>asort</function>, + <function>arsort</function>,<function>ksort</function>, + <function>natsort</function>, and <function>rsort</function>. + </para> + </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 +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 +--> +