cvs: phpdoc /de/functions array.xml

From: Date: Fri, 18 May 2001 07:47:17 +0000
Subject: cvs: phpdoc /de/functions array.xml
Groups: php.doc 
Request: Send a blank email to phpdoc+get-969335407@lists.php.net to get a copy of this message
zimt Fri May 18 00:47:17 2001 EDT Modified files: /phpdoc/de/functions array.xml Log: changes by thomas =) changes: file complete against en-Vers. 1.68 (+10 funcs & intro), and some transl-drafts.

Index: phpdoc/de/functions/array.xml diff -u phpdoc/de/functions/array.xml:1.10 phpdoc/de/functions/array.xml:1.11 --- phpdoc/de/functions/array.xml:1.10 Sun Apr 8 10:11:02 2001 +++ phpdoc/de/functions/array.xml Fri May 18 00:47:17 2001 @@ -1,12 +1,31 @@ <reference id="ref.array"> <title>Array Funktionen</title> <titleabbrev>Arrays</titleabbrev> + <partintro> + <simpara> + Diese Funktionen erlauben es, Arrays auf verschiedene Arten zu + manipulieren bzw. mit ihnen zu interagieren. Arrays sind wichtig, um + Gruppen von Variablen zu verwalten, zu bearbeiten, oder zu speichern. + </simpara> + <simpara> + Es werden einfache und mehrdimensionale Arrays unterstützt, welche + entweder vom Benutzer oder von einer anderen Funktion erstellt werden + können. Es gibt bestimmte Datenbankfunktionen, welche die Ergebnisse + aus Datenbankabfragen in Arrays speichern, und verschiedene andere + Funktionen, die Arrays als Rückgabewerte haben. + </simpara> + <para> + Siehe auch <function>is_array</function>, <function>explode</function>, + <function>implode</function>, <function>split</function>, + und <function>join</function>. + </para> + </partintro> <refentry id="function.array"> <refnamediv> <refname>array</refname> <refpurpose> - Einen Array erstellen + Erstellt ein Array </refpurpose> </refnamediv> <refsect1> @@ -14,254 +33,668 @@ <funcsynopsis> <funcprototype> <funcdef>array <function>array</function></funcdef> - <varargs/> + <paramdef>mixed + <parameter><optional>...</optional></parameter> + </paramdef> </funcprototype> </funcsynopsis> <para> - Gibt einen Array von Parametern zurück. Mit dem - <literal>=&gt;</literal> Operator können diese Parameter - indiziert werden. - <note> - <para> - <function>array</function> ist ein Sprachkonstrukt, das - benutzt wird um ein buchstäbliches Wertfeld zu erzeugen, - und nicht eine reguläre Funktion. - </para> - </note></para> - + Gibt ein den Parametern entsprechendes Array zurück. Mit dem + <literal>=&gt;</literal> Operator können die Parameter indiziert werden. + </para> + <para> + <note> + <para> + <function>Array</function> ist keine richtige Funktion sondern ein + Sprachkonstrukt, das zur Erzeugung eines Wertefeldes genutzt wird. + </para> + </note> + </para> + <para> + Die Syntax "Index =&gt; Werte", durch Kommas getrennt, definiert + Index und Werte. Index kann vom Typ String oder numerisch sein. + Wird der Index weggelassen, erstellt die Funktion automatisch einen + numerischen Index, der bei 0 beginnt. Ist der Index als Integer-Wert + angegeben, wird der nächste generierte Index der größte Integer + Index + 1. Beachten Sie, dass wenn zwei identische Indexe definiert + sind, der letzte den ersten überschreibt. + </para> <para> - Das folgende Beispiel zeigt, wie man einen zwei-dimensionalen - Array erzeugt, wie man Schlüssel für assoziative Arrays festlegt - und wie man in normalen Arrays numerische Indizes überspringt und + Das folgende Beispiel zeigt wie man ein zweidimensionales Array + erstellt, wie man Schlüssel für assoziative Arrays festlegt, und + wie man numerische Indizes in normalen Arrays überspringt und fortsetzt. - <example> - <title><function>array</function>-Beispiel</title> - <programlisting> -$fruits = array( - "fruechte" => array("a"=>"orange","b"=>"banane","c"=>"apfel"), - "zahlen" => array(1, 2, 3, 4, 5, 6), - "luecken" => array("erstes", 5 => "zweites", "drittes") + <title><function>Array</function></title> + <programlisting role="php"> +$fruechte = array ( + "fruechte" =&gt; array ("a"=&gt;"orange", "b"=&gt;"banane", "c"=&gt;"apfel"), + "zahlen" =&gt; array (1, 2, 3, 4, 5, 6), + "loecher" =&gt; array ("erstes", 5 =&gt; "zweites", "drittes") ); -</programlisting></example></para> - + </programlisting> + </example> + </para> <para> - See also: - <function>list</function>.</para> + <example> + <title>Automatischer Index mit <function>Array</function></title> + <programlisting role="php"> +$array = array( 1, 1, 1, 1, 1, 8=>1, 4=>1, 19, 3=>13); +print_r($array); + </programlisting> + </example> + wird folgendes anzeigen: + <informalexample> + <programlisting> +Array +( + [0] => 1 + [1] => 1 + [2] => 1 + [3] => 13 + [4] => 1 + [8] => 1 + [9] => 19 +) + </programlisting> + </informalexample> + Beachten Sie, daß Index '3' doppelt definiert ist, und den letzten + definierten Wert 13 behält. Index 4 wurde nach dem Index 8 definiert, + und der nächste generierte Index (Wert 19) ist 9, da der größte Index + 8 war. + </para> + <para> + Dieses Beispiel erstellt ein auf dem Index 1 basierendes Array. + <example> + <title>1-basierter Index mit <function>Array</function></title> + <programlisting role="php"> + $erstesquartal = array(1 => 'Januar', 'Februar', 'März'); + print_r($erstesquartal); + </programlisting> + </example> + wird folgendes ausgeben: + <informalexample> + <programlisting> +Array +( + [1] => 'Januar' + [2] => 'Februar' + [3] => 'März' +) + </programlisting> + </informalexample> + </para> + <para> + Siehe auch: <function>list</function>. + </para> </refsect1> </refentry> <refentry id="function.array-count-values"> <refnamediv> <refname>array_count_values</refname> - <refpurpose>Counts all the values of an array</refpurpose> + <refpurpose>Zählt die Werte eines Arrays</refpurpose> </refnamediv> <refsect1> - <title>Description</title> + <title>Beschreibung</title> <funcsynopsis> <funcprototype> <funcdef>array <function>array_count_values</function></funcdef> <paramdef>array <parameter>input</parameter></paramdef> </funcprototype> </funcsynopsis> - + <para> + <function>Array_count_values</function> gibt ein Array zurück, in dem + die Werte des Arrays <parameter>input</parameter> als Schlüssel, und + deren Anzahl als Werte angegeben sind. + </para> <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> + <example> + <title><function>Array_count_values</function></title> + <programlisting role="php"> +$array = array (1, "hello", 1, "world", "hello"); +array_count_values ($array); // liefert array (1=&gt;2, "hello"=&gt;2, "world"=&gt;1) + </programlisting> + </example> + </para> + </refsect1> + </refentry> + <refentry id="function.array-diff"> + <refnamediv> + <refname>array_diff</refname> + <refpurpose>Ermittelt die Unterschiede von Arrays</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_diff</function></funcdef> + <paramdef>array <parameter>array1</parameter></paramdef> + <paramdef>array <parameter>array2</parameter></paramdef> + <paramdef>array + <parameter><optional> ...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>Array_diff</function> gibt ein Array mit allen Werten von + <parameter>array1</parameter>, welche in keinem der anderen Argumente + enthalten sind, zurück. Beachten Sie, daß Schlüssel erhalten bleiben. + </para> <para> <example> - <title><function>array_count_values</function> example</title> - <programlisting> -$array = array(1,"hello",1,"world","hello"); -array_count_values($array); // returns array(1=>2, "hello"=>2, "world"=>1) + <title><function>Array_diff</function></title> + <programlisting role="php"> +$array1 = array ("a" =&gt; "grün", "rot", "blau"); +$array2 = array ("b" =&gt; "grün", "gelb", "rot"); +$result = array_diff ($array1, $array2); </programlisting> </example> + </para> + <para> + Dies speichert <literal>array("blau");</literal> in <varname>$result</varname>. + </para> + <para> + Siehe auch <function>array_intersect</function>. + </para> + </refsect1> + </refentry> - <note> - <para> - This function was added in PHP 4.0.</para> - </note></para> + <refentry id="function.array-filter"> + <refnamediv> + <refname>array_filter</refname> + <refpurpose>Filtert Elemente eines Arrays mittels einer + Callback-Funktion</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_filter</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>mixed + <parameter><optional>callback</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>Array_filter</function> gibt ein Array mit den mittels der + Callback-Funktion gefilterten Elementen von <parameter>input</parameter> + zurück. Ist <parameter>input</parameter> ein assoziatives Array, bleiben + die Schlüssel erhalten. + </para> + <para> + <example> + <title><function>Array_filter</function></title> + <programlisting role="php"> +function ungerade($var) { + return ($var % 2 == 1); +} + +function gerade($var) { + return ($var % 2 == 0); +} + +$array1 = array ("a"=&gt;1, "b"=&gt;2, "c"=&gt;3, "d"=&gt;4, "e"=&gt;5); +$array2 = array (6, 7, 8, 9, 10, 11, 12); + +$ungerade_arr = array_filter($array1, "ungerade"); +$gerade_arr = array_filter($array2, "gerade"); + </programlisting> + </example> + </para> + <para> + Dies speichert <literal>array ("a"=&gt;1, "c"=&gt;3, "e"=&gt;5);</literal> + in <varname>$ungerade_arr</varname>, und + <literal>array (6, 8, 10, 12);</literal> in <varname>$gerade_arr</varname>. + </para> + <para> + Siehe auch <function>array_map</function>, + <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> + <refpurpose>Vertauscht Werte und Schlüssel in einem Array</refpurpose> </refnamediv> <refsect1> - <title>Description</title> + <title>Beschreibung</title> <funcsynopsis> <funcprototype> <funcdef>array <function>array_flip</function></funcdef> <paramdef>array <parameter>trans</parameter></paramdef> </funcprototype> </funcsynopsis> - + <para> + <function>Array_flip</function> Gibt ein Array in umgekehrter + Reihenfolge zurück, d.h. Schlüssel von <parameter>trans</parameter> + werden Werte, und umgekehrt werden die Werte zu Schlüsseln. Beachten + Sie, dass <function>array_flip</function> nur mit den Typen Integer + und String arbeitet und eine Fehlermeldung ausgibt, wenn ein ungültiger + Schlüssel oder Wert entdeckt wird (z.B. vom Typ Array, Double, Object, + Boolean). + </para> <para> - <function>array_flip</function> returns an array in flip order. + Kommt ein Wert mehrmals vor, wird der letzte Schlüssel mit seinem Wert + vertauscht, und alle anderen Schlüssel- Wertepaare gehen verloren. </para> <para> + <function>array_flip</function> gibt im Fehlerfall + <literal>FALSE</literal> zurück. + </para> + <para> <example> - <title><function>array_flip</function> example</title> + <title><function>Array_flip</function> Beispiel</title> <programlisting role="php"> $trans = array_flip ($trans); $original = strtr ($str, $trans); </programlisting> </example> - - <note> - <para> - This function was added in PHP 4.0. - </para> - </note></para> + </para> + <para> + <example> + <title><function>Array_flip</function> Beispiel: Kollision</title> + <programlisting role="php"> +$trans = array ("a" => 1, "b" => 1, "c" => 2); +$trans = array_flip ($trans); +// nun enthält $trans : array(1 => "b", 2 => "c"); + </programlisting> + </example> + </para> + </refsect1> + </refentry> + <refentry id="function.array-intersect"> + <refnamediv> + <refname>array_intersect</refname> + <refpurpose>Ermittelt die Schnittmenge von Arrays</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_intersect</function></funcdef> + <paramdef>array <parameter>array1</parameter></paramdef> + <paramdef>array <parameter>array2</parameter></paramdef> + <paramdef>array + <parameter><optional> ...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>Array_intersect</function> gibt ein Array mit allen Werten + von <parameter>array1</parameter>, die auch in allen anderen + Argumenten enthalten sind, zurück. Beachten Sie, daß die Schlüssel + erhalten bleiben. + </para> + <para> + <example> + <title><function>Array_intersect</function> Beispiel</title> + <programlisting role="php"> +$array1 = array ("a" =&gt; "grün", "rot", "blau"); +$array2 = array ("b" =&gt; "grün", "gelb", "rot"); +$result = array_intersect ($array1, $array2); + </programlisting> + </example> + </para> + <para> + Dies speichert <literal>array ("a" =&gt; "grün", "rot");</literal> in + <varname>$result</varname> + </para> + <para> + Siehe auch <function>array_diff</function>. + </para> </refsect1> </refentry> <refentry id="function.array-keys"> <refnamediv> <refname>array_keys</refname> - <refpurpose>Return all the keys of an array</refpurpose> + <refpurpose>Liefert alle Schlüssel eines Arrays</refpurpose> </refnamediv> <refsect1> - <title>Description</title> + <title>Beschreibung</title> <funcsynopsis> <funcprototype> <funcdef>array <function>array_keys</function></funcdef> <paramdef>array <parameter>input</parameter></paramdef> <paramdef>mixed - <parameter><optional>search_value</optional></parameter></paramdef> + <parameter> + <optional>search_value</optional> + </parameter> + </paramdef> </funcprototype> </funcsynopsis> - + <para> + <function>Array_keys</function> gibt die Schlüssel (numerisch und + String) des Arrays <parameter>input</parameter> zurück. + </para> <para> - <function>array_keys</function> returns the keys, numeric and - string, from the <parameter>input</parameter> array.</para> + Ist der optionale Parameter <parameter>search_value</parameter> + angegeben, werden nur die Schlüssel für diesen Wert zurückgegeben. + Andernfalls werden all Schlüssel von <parameter>input</parameter> + zurückgegeben. + </para> + <para> + <example> + <title><function>Array_keys</function></title> + <programlisting role="php"> +$array = array (0 =&gt; 100, "farbe" =&gt; "rot"); +array_keys ($array); // liefert array (0, "color") +$array = array ("blau", "rot", "grün", "blau", "blau"); +array_keys ($array, "blau"); // liefert array (0, 3, 4) + +$array = array ("farbe" =&gt; array("blau", "rot", "grün"), "grösse" =&gt; array("klein", "mittel", "gross")); +array_keys ($array); // liefert array ("farbe", "grösse") + </programlisting> + </example> + </para> + <note> + <para> + Diese Funktion wurde in PHP 4 eingeführt, nachstehend finden Sie eine + Implementierung für Benutzer von PHP 3. + <example> + <title> + Implementierung von <function>array_keys</function> für Benutzer von PHP 3: + </title> + <programlisting role="php"> +function array_keys ($arr, $term="") { + $t = array(); + while (list($k,$v) = each($arr)) { + if ($term &amp;&amp; $v != $term) + continue; + $t[] = $k; + } + return $t; +} + </programlisting> + </example> + </para> + </note> <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> + Siehe auch <function>array_values</function>. + </para> + </refsect1> + </refentry> + <refentry id="function.array-map"> + <refnamediv> + <refname>array_map</refname> + <refpurpose>Wendet eine Callback-Funktion auf die Elemente von Arrays + an</refpurpose> + </refnamediv> + <refsect1> + <title>Beschreibung</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_map</function></funcdef> + <paramdef>mixed <parameter>callback</parameter></paramdef> + <paramdef>array <parameter>arr1</parameter></paramdef> + <paramdef>array + <parameter><optional>arr2...</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>Array_map</function> wendet die Callback-Funktion auf alle + Elemente von <parameter>arr1</parameter> an, und gibt ein Array mit + den modifizierten Werten zurück. + </para> <para> <example> - <title><function>array_keys</function> example</title> - <programlisting> -$array = array(0 => 100, "color" => "red"); -array_keys($array); // returns array(0, "color") + <title><function>Array_map</function></title> + <programlisting role="php"> +function cube($n) { + return $n*$n*$n; +} -$array = array(1, 100, 2, 100); -array_keys($array, 100); // returns array(0, 2) +$a = array(1, 2, 3, 4, 5); +$b = array_map("cube", $a); </programlisting> - </example></para> - + </example> + </para> <para> - See also <function>array_values</function>. + Dies speichert <literal>array (1, 8, 27, 64, 125);</literal> + in <varname>$b</varname>. + + </para> + <para> + <example> + <title><function>Array_map</function> - Verwendung mehrerer Arrays</title> + <programlisting role="php"> +function show_Spanish($n, $m) { + return "Die Zahl $n heißt auf Spanish $m"; +} - <note> - <para> - This function was added in PHP 4.0.</para> - </note></para> +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); + +// will output: +// Array +// ( +// [0] => Die Zahl 1 heißt auf Spanish uno +// [1] => Die Zahl 2 heißt auf Spanish dos +// [2] => Die Zahl 3 heißt auf Spanish tres +// [3] => Die Zahl 4 heißt auf Spanish cuatro +// [4] => Die Zahl 5 heißt auf Spanish cinco +// ) + +$d = array_map("map_Spanish", $a , $b); + +print_r($d); + +// will output: +// Array +// ( +// [0] => Array +// ( +// [1] => uno +// ) +// +// [1] => Array +// ( +// [2] => dos +// ) +// +// [2] => Array +// ( +// [3] => tres +// ) +// +// [3] => Array +// ( +// [4] => cuatro +// ) +// +// [4] => Array +// ( +// [5] => cinco +// ) +// +// ) + </programlisting> + </example> + </para> + <para> + Bei Verwendung von zwei oder mehr Arrays sollten diese gewöhnlich die + gleiche Länge besitzen, da die Callback-Funktion parallel auf die + entsprechenden Elemente angewandt wird. + Haben die Arrays unterschiedliche Längen, wird das kürzeste um leere + Elemente erweitert. + </para> + <para> + Eine interessante Anwendung dieser Funktion ist die Konstruktion eines + Arrays bestehend aus Arrays, was mit <literal>null</literal> als Name + der Callback-Funktion leicht realisiert werden kann. + </para> + <para> + <example> + <title><function>Array_map</function> - Erstellen eines Arrays mit + Arrays</title> + <programlisting role="php"> +$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); + +// will output: +// 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 +// ) +// +// ) + </programlisting> + </example> + </para> + <para> + Siehe auch <function>array_filter</function>, + <function>array_reduce</function>. + </para> </refsect1> </refentry> <refentry id="function.array-merge"> <refnamediv> <refname>array_merge</refname> - <refpurpose>Merge two or more arrays</refpurpose> + <refpurpose>Zusammenführen von zwei oder mehr Arrays</refpurpose> </refnamediv> <refsect1> - <title>Description</title> + <title>Beschreibung</title> <funcsynopsis> <funcprototype> <funcdef>array <function>array_merge</function></funcdef> <paramdef>array <parameter>array1</parameter></paramdef> <paramdef>array <parameter>array2</parameter></paramdef> - <paramdef> - <parameter><optional> ...</optional></parameter> + <paramdef>array + <parameter><optional>...</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> - <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> - + <function>Array_merge</function> fügt die Elemente von zwei oder mehr + Arrays zusammen, indem die Werte des einen an das Ende des anderen + angehängt werden. Das daraus resultierende Array wird zurückgegeben. + </para> <para> - If the input arrays had the same string keys, then the later - value for that key will overwrite previous one. If, however, the - arrays have the same numeric key, this does not happen since the - values are appended.</para> - + Haben die angegebenen Arrays die selben String-Schlüssel, dann wird der + hintere Wert dieses Schlüssels den vorhergehenden überschreiben. Haben + die Arrays den gleichen numerischen Schlüssel, dann wird der hintere + Wert den vorhergehenden nicht überschreiben, sondern an den vorderen + angehängt. + </para> <para> <example> - <title><function>array_merge</function> example</title> - <programlisting> -$array1 = array("color" => "red", 2, 4); -$array2 = array("a", "b", "color" => "green", "shape" => "trapezoid"); -array_merge($array1, $array2); + <title><function>array_merge</function></title> + <programlisting role="php"> +$array1 = array ("farbe" =&gt; "rot", 2, 4); +$array2 = array ("a", "b", "farbe" =&gt; "grün", "form" =&gt; "trapezoid", 4); +array_merge ($array1, $array2); </programlisting> - <para> - Resulting array will be array("color" => "green", 2, 4, "a", - "b", "shape" => "trapezoid").</para> </example> - - <note> - <para> - This function was added in PHP 4.0.</para> - </note></para> + </para> + <para> + Das resultierende Array wird <literal>array("farbe" =&gt; "grün", 2, 4, + "a", "b", "form" =&gt; "trapezoid", 4)</literal>. + </para> + <para> + Siehe auch <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> + <refpurpose>Rekursives Zusammenführen von zweioder mehr Arrays</refpurpose> </refnamediv> <refsect1> - <title>Description</title> + <title>Beschreibung</title> <funcsynopsis> <funcprototype> <funcdef>array <function>array_merge_recursive</function></funcdef> <paramdef>array <parameter>array1</parameter></paramdef> <paramdef>array <parameter>array2</parameter></paramdef> - <paramdef> - <parameter><optional> ...</optional></parameter> + <paramdef>array + <parameter><optional>...</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> <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. + <function>Array_merge_recursive</function> fügt die Elemente von zwei + oder mehr Arrays zusammen, so dass die Werte des einen Arrays an die + des vorigen angehängt werden. Das daraus resultierende Array wird + zurückgegeben. </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. + Haben die angegebenen Arrays die selben String-Schlüssel, dann wird der + hintere Wert dieses Schlüssels den vorhergehenden überschreiben. Haben + die Arrays den gleichen numerischen Schlüssel, dann wird der hintere + Wert den vorhergehenden nicht überschreiben, sondern an den vorderen + angehängt. </para> <para> <example> - <title><function>array_merge_recursive</function> example</title> + <title><function>Array_merge_recursive</function> example</title> <programlisting role="php"> -$ar1 = array("color" => array("favorite" => "red"), 5); -$ar2 = array(10, "color" => array("favorite" => "green", "blue")); -$result = array_merge_recursive($ar1, $ar2); +$ar1 = array ("color" =&gt; array ("favorite" =&gt; "red"), 5); +$ar2 = array (10, "color" =&gt; array ("favorite" =&gt; "green", "blue")); +$result = array_merge_recursive ($ar1, $ar2); </programlisting> - <para> - Resulting array will be array("color" => array("favorite" => - array("red", "green"), "blue"), 5, 10). - </para> </example> </para> <para> + Resulting array will be <literal>array ("color" =&gt; array + ("favorite" =&gt; array ("red", "green"), "blue"), 5, 10)</literal>. + </para> + <para> See also <function>array_merge</function>. </para> </refsect1> @@ -281,17 +714,19 @@ <paramdef>mixed <parameter><optional>arg</optional></parameter> </paramdef> - <paramdef> + <paramdef>mixed + <parameter><optional>...</optional></parameter> + </paramdef> + <paramdef>array <parameter><optional>...</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> <para> - <function>array_multisort</function> can be used to sort several + <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 @@ -299,14 +734,12 @@ (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> @@ -318,7 +751,6 @@ </listitem> </itemizedlist> </para> - <para> Sorting type flags: <itemizedlist> @@ -333,53 +765,57 @@ </listitem> </itemizedlist> </para> - <para> No two sorting flags of the same type can be specified after each array. The sortings 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. + Returns <literal>TRUE</literal> on success, <literal>FALSE</literal> + on failure. </para> - - <example> - <title>Sorting multiple arrays</title> - <programlisting role="php"> -$ar1 = array("10", 100, 100, "a"); -$ar2 = array(1, 3, "2", 1); -array_multisort($ar1, $ar2); - </programlisting> - <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> - </example> - - <example> - <title>Sorting multi-dimensional array</title> - <programlisting role="php"> -$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> - <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> - </example> + <para> + <example> + <title>Sorting multiple arrays</title> + <programlisting role="php"> +$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"> +$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> + <refpurpose> + Pad array to the specified length with a value + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -391,9 +827,8 @@ <paramdef>mixed <parameter>pad_value</parameter></paramdef> </funcprototype> </funcsynopsis> - <para> - <function>array_pad</function> returns a copy of the + <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 @@ -403,20 +838,19 @@ 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> -$input = array(12, 10, 9); + <title><function>Array_pad</function> example</title> + <programlisting role="php"> +$input = array (12, 10, 9); -$result = array_pad($input, 5, 0); -// result is array(12, 10, 9, 0, 0) +$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, -7, -1); +// result is array (-1, -1, -1, -1, 12, 10, 9) -$result = array_pad($input, 2, "noop"); +$result = array_pad ($input, 2, "noop"); // not padded </programlisting> </example> @@ -437,33 +871,32 @@ <paramdef>array <parameter>array</parameter></paramdef> </funcprototype> </funcsynopsis> - <para> - <function>array_pop</function> pops and returns the last value of + <function>Array_pop</function> pops and returns the last value of the <parameter>array</parameter>, shortening the - <parameter>array</parameter> by one element.</para> - + <parameter>array</parameter> by one element. + If <parameter>array</parameter> is empty (or is not an array), + <varname>NULL</varname> will be returned. + </para> <para> <example> - <title><function>array_pop</function> example</title> - <programlisting> -$stack = array("orange", "apple", "raspberry"); -$fruit = array_pop($stack); + <title><function>Array_pop</function> example</title> + <programlisting role="php"> +$stack = array ("orange", "apple", "raspberry"); +$fruit = array_pop ($stack); </programlisting> - <para> - After this, $stack has only 2 elements: "orange" and "apple", - and $fruit has "raspberry".</para> - </example></para> - + </example> + </para> + <para> + After this, <varname>$stack</varname> has only 2 elements: + "orange" and "apple", and <varname>$fruit</varname> has + "raspberry". + </para> <para> See also <function>array_push</function>, <function>array_shift</function>, and <function>array_unshift</function>. - - <note> - <para> - This function was added in PHP 4.0.</para> - </note></para> + </para> </refsect1> </refentry> @@ -481,52 +914,52 @@ <funcdef>int <function>array_push</function></funcdef> <paramdef>array <parameter>array</parameter></paramdef> <paramdef>mixed <parameter>var</parameter></paramdef> - <paramdef><parameter><optional>...</optional></parameter></paramdef> + <paramdef>mixed + <parameter><optional>...</optional></parameter> + </paramdef> </funcprototype> </funcsynopsis> - <para> - <function>array_push</function> treats + <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> + <programlisting role="php"> $array[] = $var; </programlisting> - repeated for each <parameter>var</parameter>.</para> - + repeated for each <parameter>var</parameter>. + </para> <para> - Returns the new number of elements in the array.</para> - + Returns the new number of elements in the array. + </para> <para> <example> - <title><function>array_push</function> example</title> - <programlisting> -$stack = array(1, 2); -array_push($stack, "+", 3); + <title><function>Array_push</function> example</title> + <programlisting role="php"> +$stack = array (1, 2); +array_push ($stack, "+", 3); </programlisting> </example> - This example would result in $stack having 4 elements: 1, 2, "+", - and 3.</para> - + </para> <para> - See also: - <function>array_pop</function>, + This example would result in <varname>$stack</varname> having 4 + elements: 1, 2, "+", and 3. + </para> + <para> + See also: <function>array_pop</function>, <function>array_shift</function>, and <function>array_unshift</function>. - - <note> - <para> - This function was added in PHP 4.0.</para> - </note></para> + </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> + <refpurpose> + Pick one or more random entries out of an array + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -540,32 +973,29 @@ </funcprototype> </funcsynopsis> <para> - <function>array_rand</function> is rather useful when you want to + <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> + <title><function>Array_rand</function> example</title> <programlisting role="php"> -srand((double)microtime() * 10000000); -$input = array("Neo", "Morpheus", "Trinity", "Cypher", "Tank"); -$rand_keys = array_rand($input, 2); +srand ((double) 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> @@ -577,7 +1007,9 @@ <refentry id="function.array-reverse"> <refnamediv> <refname>array_reverse</refname> - <refpurpose>Return an array with elements in reverse order</refpurpose> + <refpurpose> + Return an array with elements in reverse order + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -585,33 +1017,107 @@ <funcprototype> <funcdef>array <function>array_reverse</function></funcdef> <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>bool <parameter><optional>preserve_keys</optional></parameter></paramdef> </funcprototype> </funcsynopsis> - <para> - <function>array_reverse</function> takes input <parameter>array</parameter> and returns a new array with the order of the elements reversed.</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 <literal>TRUE</literal>. + </para> <para> <example> - <title><function>array_reverse</function> example</title> - <programlisting> -$input = array("php", 4.0, array("green", "red")); -$result = array_reverse($input); + <title><function>Array_reverse</function> example</title> + <programlisting role="php"> +$input = array ("php", 4.0, array ("green", "red")); +$result = array_reverse ($input); +$result_keyed = array_reverse ($input, TRUE); </programlisting> </example> - This makes $result have array(array("green", "red"), 4.0, "php"). + </para> + <para> + This makes both <varname>$result</varname> and <varname>$result_keyed</varname> + be <literal>array(array ("green", "red"), 4.0, "php")</literal>. But + <varname>$result_keyed[0]</varname> is still + <literal>"php"</literal>. + </para> + <note> + <para> + The second parameter was added in PHP 4.0.3. + </para> + </note> + </refsect1> + </refentry> - <note> - <para> - This function was added in PHP 4.0 Beta 3.</para> - </note></para> + <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>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_reduce</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>mixed <parameter>callback</parameter></paramdef> + <paramdef>int + <parameter><optional>initial</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <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>intial</parameter> is + avaliable, 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"> +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>, + <function>array_map</function>. + </para> </refsect1> </refentry> <refentry id="function.array-shift"> <refnamediv> <refname>array_shift</refname> - <refpurpose>Pop an element off the beginning of array</refpurpose> + <refpurpose> + Pop an element off the beginning of array + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -621,33 +1127,32 @@ <paramdef>array <parameter>array</parameter></paramdef> </funcprototype> </funcsynopsis> - <para> - <function>array_shift</function> shifts the first value of the + <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.</para> - + down. + If <parameter>array</parameter> is empty (or is not an array), + <varname>NULL</varname> will be returned. + </para> <para> <example> - <title><function>array_shift</function> example</title> - <programlisting> -$args = array("-v", "-f"); -$opt = array_shift($args); + <title><function>Array_shift</function> example</title> + <programlisting role="php"> +$args = array ("-v", "-f"); +$opt = array_shift ($args); </programlisting> </example> - This would result in $args having one element "-f" left, and $opt - being "-v".</para> - + </para> <para> + This would result in <varname>$args</varname> having one element + "-f" left, and <varname>$opt</varname> being "-v". + </para> + <para> See also <function>array_unshift</function>, <function>array_push</function>, and <function>array_pop</function>. - - <note> - <para> - This function was added in PHP 4.0.</para> - </note></para> + </para> </refsect1> </refentry> @@ -670,19 +1175,18 @@ </paramdef> </funcprototype> </funcsynopsis> - <para> - <function>array_slice</function> returns a sequence of elements + <function>Array_slice</function> returns a sequence of elements from the <parameter>array</parameter> specified by the <parameter>offset</parameter> and <parameter>length</parameter> - parameters.</para> - + 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> - + 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 @@ -690,28 +1194,24 @@ 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> - + <parameter>array</parameter>. + </para> <para> <example> - <title><function>array_slice</function> examples</title> - <programlisting> -$input = array("a", "b", "c", "d", "e"); + <title><function>Array_slice</function> examples</title> + <programlisting role="php"> +$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" +$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> - + </example> + </para> <para> See also <function>array_splice</function>. - - <note> - <para> - This function was added in PHP 4.0.</para> - </note></para> + </para> </refsect1> </refentry> @@ -734,25 +1234,27 @@ <parameter><optional>length</optional></parameter> </paramdef> <paramdef>array - <parameter><optional>replacement</optional></parameter></paramdef> + <parameter> + <optional>replacement</optional> + </parameter> + </paramdef> </funcprototype> </funcsynopsis> - <para> - <function>array_splice</function> removed the elements designated + <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.</para> - + supplied. + </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> - + 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 @@ -764,8 +1266,8 @@ <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> - + <parameter>length</parameter>. + </para> <para> If <parameter>replacement</parameter> array is specified, then the removed elements are replaced with elements from this array. @@ -775,52 +1277,121 @@ 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> - + around it, unless the element is an array itself. + </para> <para> The following equivalences hold: <programlisting> -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> +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"> +$input = array ("red", "green", "blue", "yellow"); + +array_splice ($input, 2); // $input is now array ("red", "green") +array_splice ($input, 1, -1); // $input is now array ("red", "yellow") +array_splice ($input, 1, count($input), "orange"); + // $input is now array ("red", "orange") +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>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_sum</function></funcdef> + <paramdef>array <parameter>arr</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <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"> +$a = array(2,4,6,8); +echo "sum(a) = ".array_sum($a)."\n"; +// prints: sum(a) = 20 + +$b = array("a"=>1.2,"b"=>2.3,"c"=>3.4); +echo "sum(b) = ".array_sum($b)."\n"; +// prints: sum(b) = 6.9 + </programlisting> + </example> + </para> + </refsect1> + </refentry> + <refentry id="function.array-unique"> + <refnamediv> + <refname>array_unique</refname> + <refpurpose>Removes duplicate values from an array</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>array_unique</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> <para> - Returns the array consisting of removed elements.</para> - + <function>Array_unique</function> takes input + <parameter>array</parameter> and returns a new array + without duplicate values. + Note that keys are preserved. + </para> <para> <example> - <title><function>array_splice</function> examples</title> - <programlisting> -$input = array("red", "green", "blue", "yellow"); - -array_splice($input, 2); // $input is now array("red", "green") -array_splice($input, 1, -1); // $input is now array("red", "yellow") -array_splice($input, 1, count($input), "orange"); - // $input is now array("red", "orange") -array_splice($input, -1, 1, array("black", "maroon")); - // $input is now array("red", "green", - // "blue", "black", "maroon") + <title><function>Array_unique</function> example</title> + <programlisting role="php"> +$input = array ("a" =&gt; "green", "red", "b" =&gt; "green", "blue", "red"); +$result = array_unique ($input); </programlisting> - </example></para> - + </example> + </para> <para> - See also <function>array_slice</function>. - - <note> - <para> - This function was added in PHP 4.0.</para> - </note></para> + This makes <varname>$result</varname> have <literal>array ("a" =&gt; + "green", "red", "blue");</literal>. + </para> </refsect1> </refentry> <refentry id="function.array-unshift"> <refnamediv> <refname>array_unshift</refname> - <refpurpose>Push one or more elements - onto the beginning of array</refpurpose> + <refpurpose> + Push one or more elements onto the beginning of array + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -829,40 +1400,41 @@ <funcdef>int <function>array_unshift</function></funcdef> <paramdef>array <parameter>array</parameter></paramdef> <paramdef>mixed <parameter>var</parameter></paramdef> - <paramdef><parameter><optional>...</optional></parameter></paramdef> + <paramdef>mixed + <parameter> + <optional>...</optional> + </parameter> + </paramdef> </funcprototype> </funcsynopsis> - <para> - <function>array_unshift</function> prepends passed elements to + <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> - + elements stay in the same order. + </para> <para> Returns the new number of elements in the - <parameter>array</parameter>.</para> - + <parameter>array</parameter>. + </para> <para> <example> - <title><function>array_unshift</function> example</title> - <programlisting> -$queue = array("p1", "p3"); -array_unshift($queue, "p4", "p5", "p6"); + <title><function>Array_unshift</function> example</title> + <programlisting role="php"> +$queue = array ("p1", "p3"); +array_unshift ($queue, "p4", "p5", "p6"); </programlisting> </example> - This would result in $queue having 5 elements: "p4", "p5", "p6", - "p1", and "p3".</para> - + </para> + <para> + This would result in <varname>$queue</varname> having 5 + elements: "p4", "p5", "p6", "p1", and "p3". + </para> <para> See also <function>array_shift</function>, <function>array_push</function>, and <function>array_pop</function>. - - <note> - <para> - This function was added in PHP 4.0.</para> - </note></para> + </para> </refsect1> </refentry> @@ -879,24 +1451,40 @@ <paramdef>array <parameter>input</parameter></paramdef> </funcprototype> </funcsynopsis> - <para> <function>array_values</function> returns all the values from the - <parameter>input</parameter> array.</para> - + <parameter>input</parameter> array. + </para> <para> <example> - <title><function>array_values</function> example</title> - <programlisting> -$array = array("size" => "XL", "color" => "gold"); -array_values($array); // returns array("XL", "gold") + <title><function>Array_values</function> example</title> + <programlisting role="php"> +$array = array ("size" =&gt; "XL", "color" =&gt; "gold"); +array_values ($array); // returns array ("XL", "gold") </programlisting> </example> - - <note> - <para> - This function was added in PHP 4.0.</para> - </note></para> + </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"> +function array_values ($arr) { + $t = array(); + while (list($k, $v) = each ($arr)) { + $t[] = $v; + } + return $t; +} + </programlisting> + </example> + </para> + </note> </refsect1> </refentry> @@ -904,7 +1492,7 @@ <refnamediv> <refname>array_walk</refname> <refpurpose> - Apply a user function to every member of an array. + Apply a user function to every member of an array </refpurpose> </refnamediv> <refsect1> @@ -917,24 +1505,23 @@ <paramdef>mixed <parameter>userdata</parameter></paramdef> </funcprototype> </funcsynopsis> - <simpara> Applies the function named by <parameter>func</parameter> to each - element of - <parameter>arr</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. - + element of <parameter>arr</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. + </simpara> + <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> - + call, or by using <function>error_reporting</function>. + </simpara> <note> <para> If <parameter>func</parameter> needs to be working with the @@ -944,35 +1531,42 @@ itself. </para> </note> - <note> <para> - Passing the key and userdata to <parameter>func</parameter> was added in 4.0.</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> </note> - <para> <example> - <title><function>array_walk</function> example</title> - <programlisting> -$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"); + <title><function>Array_walk</function> example</title> + <programlisting role="php"> +$fruits = array ("d"=&gt;"lemon", "a"=&gt;"orange", "b"=&gt;"banana", "c"=&gt;"apple"); -function test_alter( &$item1, $key, $prefix ) { - $item1 = "$prefix: $item1"; +function test_alter (&amp;$item1, $key, $prefix) { + $item1 = "$prefix: $item1"; } -function test_print( $item2, $key ) { - echo "$key. $item2&lt;br&gt;\n"; +function test_print ($item2, $key) { + echo "$key. $item2&lt;br&gt;\n"; } -array_walk( $fruits, 'test_print' ); -array_walk( $fruits, 'test_alter', 'fruit' ); -array_walk( $fruits, 'test_print' ); +array_walk ($fruits, 'test_print'); +reset ($fruits); +array_walk ($fruits, 'test_alter', 'fruit'); +reset ($fruits); +array_walk ($fruits, 'test_print'); </programlisting> - </example></para> - + </example> + </para> <simpara> - See also <function>each</function> and <function>list</function>.</simpara> - + See also <function>each</function> and <function>list</function>. + </simpara> </refsect1> </refentry> @@ -989,6 +1583,9 @@ <funcprototype> <funcdef>void <function>arsort</function></funcdef> <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> </funcprototype> </funcsynopsis> <para> @@ -997,28 +1594,43 @@ with. This is used mainly when sorting associative arrays where the actual element order is significant. <example> - <title><function>arsort</function> example</title> - <programlisting> -$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"); -arsort($fruits); -reset($fruits); -while(list($key,$val)=each($fruits)) { - echo "$key -> $val\n"; + <title><function>Arsort</function> example</title> + <programlisting role="php"> +$fruits = array ("d"=&gt;"lemon", "a"=&gt;"orange", "b"=&gt;"banana", "c"=&gt;"apple"); +arsort ($fruits); +reset ($fruits); +while (list ($key, $val) = each ($fruits)) { + echo "$key = $val\n"; } </programlisting> </example> + </para> + <para> This example would display: - <computeroutput> + </para> + <para> + <informalexample> + <programlisting> fruits[a] = orange fruits[d] = lemon fruits[b] = banana fruits[c] = apple - </computeroutput> + </programlisting> + </informalexample> + </para> + <para> The fruits have been sorted in reverse alphabetical order, and - the index associated with each element has been maintained.</para> + 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> + <function>ksort</function>, and <function>sort</function>. + </para> </refsect1> </refentry> @@ -1033,6 +1645,7 @@ <funcprototype> <funcdef>void <function>asort</function></funcdef> <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int <parameter><optional>sort_flags</optional></parameter></paramdef> </funcprototype> </funcsynopsis> <para> @@ -1041,27 +1654,43 @@ with. This is used mainly when sorting associative arrays where the actual element order is significant. <example> - <title><function>asort</function> example</title> - <programlisting> -$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"); -asort($fruits); -reset($fruits); -while(list($key,$val)=each($fruits)) { - echo "$key -> $val\n"; + <title><function>Asort</function> example</title> + <programlisting role="php"> +$fruits = array ("d"=&gt;"lemon", "a"=&gt;"orange", "b"=&gt;"banana", "c"=&gt;"apple"); +asort ($fruits); +reset ($fruits); +while (list ($key, $val) = each ($fruits)) { + echo "$key = $val\n"; } -</programlisting></example> + </programlisting> + </example> + </para> + <para> This example would display: - <computeroutput> + </para> + <para> + <informalexample> + <programlisting> fruits[c] = apple fruits[b] = banana fruits[d] = lemon fruits[a] = orange -</computeroutput> + </programlisting> + </informalexample> + </para> + <para> The fruits have been sorted in alphabetical order, and the index - associated with each element has been maintained.</para> + 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> + <function>ksort</function>, and <function>sort</function>. + </para> </refsect1> </refentry> @@ -1077,59 +1706,58 @@ <funcsynopsis> <funcprototype> <funcdef>array <function>compact</function></funcdef> - <paramdef><parameter>string varname | array - varnames</parameter></paramdef> - <paramdef><parameter><optional>...</optional></parameter></paramdef> + <paramdef>mixed <parameter>varname</parameter></paramdef> + <paramdef>mixed + <parameter><optional>...</optional></parameter> + </paramdef> </funcprototype> </funcsynopsis> - <para> - <function>compact</function> takes a variable number of + <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> - + <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> - + 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> + <title><function>Compact</function> example</title> + <programlisting role="php"> $city = "San Francisco"; $state = "CA"; $event = "SIGGRAPH"; -$location_vars = array("city", "state"); +$location_vars = array ("city", "state"); -$result = compact("event", $location_vars); +$result = compact ("event", "nothing_here", $location_vars); </programlisting> - <para> - After this, $result will be array("event" => "SIGGRAPH", "city" - => "San Francisco", "state" => "CA").</para> - </example></para> - + After this, <varname>$result</varname> will be <literal>array ("event" + =&gt; "SIGGRAPH", "city" =&gt; "San Francisco", "state" =&gt; "CA")</literal>. + </para> + </example> + </para> <para> See also <function>extract</function>. - - <note> - <para> - This function was added in PHP 4.0.</para> - </note></para> + </para> </refsect1> </refentry> <refentry id="function.count"> <refnamediv> <refname>count</refname> - <refpurpose>count elements in a variable</refpurpose> + <refpurpose>Count elements in a variable</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1142,23 +1770,39 @@ <para> Returns the number of elements in <parameter>var</parameter>, which is typically an array (since anything else will have one - element).</para> + element). + </para> <para> - Returns 1 if the variable is not an array.</para> + Returns 1 if the variable is not an array. + </para> <para> Returns 0 if the variable is not set. - <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> + <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> <para> - See also: - <function>sizeof</function>, <function>isset</function>, and - <function>is_array</function>.</para> + <example> + <title><function>Count</function> example</title> + <programlisting role="php"> +$a[0] = 1; +$a[1] = 3; +$a[2] = 5; +$result = count ($a); +//$result == 3 + </programlisting> + </example> + </para> + <para> + See also: <function>sizeof</function>, + <function>isset</function>, and + <function>is_array</function>. + </para> </refsect1> </refentry> @@ -1178,33 +1822,33 @@ <para> Every array has an internal pointer to its "current" element, which is initialized to the first element inserted into the - array.</para> - + 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> - + <function>current</function> returns <literal>FALSE</literal>. + <warning> + <para> + If the array contains empty elements (0 or "", the empty + string) then this function will return <literal>FALSE</literal> + 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> + 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> @@ -1229,80 +1873,77 @@ <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> - + <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> - + array contents, <function>each</function> returns + <literal>FALSE</literal>. + </para> <para> <example> - <title><function>each</function> examples</title> - <programlisting> + <title><function>Each</function> examples</title> + <programlisting role="php"> $foo = array ("bob", "fred", "jussi", "jouni", "egon", "marliese"); -$bar = each( $foo ); +$bar = each ($foo); </programlisting> - <para> - <literal>$bar</literal> now contains the following key/value + <varname>$bar</varname> now contains the following key/value pairs: - <itemizedlist spacing="compact"> - <listitem><simpara>0 => 0</simpara></listitem> - <listitem><simpara>1 => 'bob'</simpara></listitem> - <listitem><simpara>key => 0</simpara></listitem> - <listitem><simpara>value => 'bob'</simpara></listitem> + <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> -$foo = array( "Robert" => "Bob", "Seppo" => "Sepi" ); -$bar = each( $foo ); - </programlisting></para> - + <programlisting role="php"> +$foo = array ("Robert" =&gt; "Bob", "Seppo" =&gt; "Sepi"); +$bar = each ($foo); + </programlisting> + </para> <para> - <literal>$bar</literal> now contains the following key/value + <varname>$bar</varname> now contains the following key/value pairs: - <itemizedlist spacing="compact"> - <listitem><simpara>0 => 'Robert'</simpara></listitem> - <listitem><simpara>1 => 'Bob'</simpara></listitem> - <listitem><simpara>key => 'Robert'</simpara></listitem> - <listitem><simpara>value => 'Bob'</simpara></listitem> - </itemizedlist></para> - - </example></para> - + <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>Each</function> is typically used in conjunction with <function>list</function> to traverse an array; for instance, - $HTTP_POST_VARS: - + <varname>$HTTP_POST_VARS</varname>: <example> <title> - Traversing $HTTP_POST_VARS with <function>each</function> + Traversing <varname>$HTTP_POST_VARS</varname> with + <function>each</function> </title> - <programlisting> + <programlisting role="php"> echo "Values submitted via POST method:&lt;br&gt;"; -while (list($key, $val) = each($HTTP_POST_VARS)) { - echo "$key => $val&lt;br&gt;"; +reset ($HTTP_POST_VARS); +while (list ($key, $val) = each ($HTTP_POST_VARS)) { + echo "$key =&gt; $val&lt;br&gt;"; } </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.</para> - + </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. + </para> <para> See also <function>key</function>, <function>list</function>, - <function>current</function>, <function>reset</function>, - <function>next</function>, and <function>prev</function>.</para> - + <function>current</function>, <function>reset</function>, + <function>next</function>, and <function>prev</function>. + </para> </refsect1> </refentry> - <refentry id="function.end"> <refnamediv> <refname>end</refname> @@ -1314,20 +1955,19 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef><function>end</function></funcdef> + <funcdef>mixed <function>end</function></funcdef> <paramdef>array <parameter>array</parameter></paramdef> </funcprototype> </funcsynopsis> <para> - <function>end</function> advances <parameter>array</parameter>'s - internal pointer to the last element.</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>end</function>, - <function>next</function>, and - <function>reset</function>.</para> + See also: <function>current</function>, + <function>each</function>, <function>end</function>, + <function>next</function>, and <function>reset</function>. + </para> </refsect1> </refentry> @@ -1342,7 +1982,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>void <function>extract</function></funcdef> + <funcdef>int <function>extract</function></funcdef> <paramdef>array <parameter>var_array</parameter></paramdef> <paramdef>int <parameter><optional>extract_type</optional></parameter> @@ -1359,94 +1999,130 @@ 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> + <parameter>prefix</parameter> parameters. + </para> + <note> + <para> + Since version 4.0.5 this function returns the number of + variables extracted. + </para> + </note> <para> - <function>extract</function> checks for colissions with existing - variables. The way collisions are treated is determined by - <parameter>extract_type</parameter>. It can be one of the + <function>extract</function> checks each key to see whether if 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> + <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> + <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 new variable with - <parameter>prefix</parameter>. - </simpara> + <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> - Prefix all variables with <parameter>prefix</parameter>. - </simpara> + <simpara> + Only prefix invalid/numeric variable names with + <parameter>prefix</parameter>. This flag has been added in PHP 4.0.5. + </simpara> </listitem> </varlistentry> - </variablelist></para> + </variablelist> + </para> <para> If <parameter>extract_type</parameter> is not specified, it is - assumed to be EXTR_OVERWRITE.</para> + assumed to be EXTR_OVERWRITE. + </para> <para> Note that <parameter>prefix</parameter> is only required if - <parameter>extract_type</parameter> is EXTR_PREFIX_SAME or - EXTR_PREFIX_ALL.</para> + <parameter>extract_type</parameter> is EXTR_PREFIX_SAME, EXTR_PREFIX_ALL, + or EXTR_PREFIX_INVALID. If the prefixed result is not a valid variable + name, it is not imported into the symbol table. + </para> <para> - <function>extract</function> checks each key to see if it - constitues a valid variable name, and if it does only then does - it proceed to import it.</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 symbol table variables contained in an associative array returned by - <function>wddx_deserialize</function>.</para> + <function>wddx_deserialize</function>. + </para> <para> <example> - <title>extract example</title> - <programlisting> -&lt;? + <title><function>Extract</function> example</title> + <programlisting role="php"> +&lt;?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"); +$var_array = array ("color" =&gt; "blue", + "size" =&gt; "medium", + "shape" =&gt; "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> + </example> + </para> + <para> + The above example will produce: + <programlisting> blue, large, sphere, medium - </programlisting></para> - + </programlisting> + </para> + <para> + The <varname>$size</varname> wasn't overwritten, becaus 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 cause <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. + </para> <para> - The $size wasn't overwritten, becaus we specified - EXTR_PREFIX_SAME, which resulted in $wddx_size being created. - If EXTR_SKIP was specified, then $wddx_size wouldn't even have - been created. EXTR_OVERWRITE would have cause $size to have - value "medium", and EXTR_PREFIX_ALL would result in new - variables being named $wddx_color, $wddx_size, and $wddx_shape.</para> + See also: <function>compact</function>. + </para> </refsect1> </refentry> @@ -1462,7 +2138,7 @@ <funcdef>bool <function>in_array</function></funcdef> <paramdef>mixed <parameter>needle</parameter></paramdef> <paramdef>array <parameter>haystack</parameter></paramdef> - <paramdef>bool + <paramdef>bool <parameter><optional>strict</optional></parameter> </paramdef> </funcprototype> @@ -1514,6 +2190,40 @@ </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>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>array_search</function></funcdef> + <paramdef>mixed <parameter>needle</parameter></paramdef> + <paramdef>array <parameter>haystack</parameter></paramdef> + <paramdef>bool <parameter>strict</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Searches <parameter>haystack</parameter> for + <parameter>needle</parameter> and returns the key if it is found in + the array, <literal>FALSE</literal> otherwise. + </para> + <para> + If the third parameter <parameter>strict</parameter> is set to + <literal>TRUE</literal> then the <function>array_search</function> + will also check the types of the <parameter>needle</parameter> + in the <parameter>haystack</parameter>. + </para> + <para> + See also <function>in_array</function>. + </para> + </refsect1> + </refentry> + <refentry id="function.key"> <refnamediv> <refname>key</refname> @@ -1528,12 +2238,12 @@ </funcprototype> </funcsynopsis> <para> - <function>key</function> returns the index element of the - current array position.</para> + <function>Key</function> returns the index element of the + current array position. + </para> <para> - See also: - <function>current</function>, - <function>next</function></para> + See also <function>current</function> and <function>next</function>. + </para> </refsect1> </refentry> @@ -1548,40 +2258,52 @@ <funcprototype> <funcdef>int <function>krsort</function></funcdef> <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> </funcprototype> </funcsynopsis> - <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> -$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"); -krsort($fruits); -reset($fruits); -while(list($key,$val)=each($fruits)) { - echo "$key -> $val\n"; + 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"> +$fruits = array ("d"=&gt;"lemon", "a"=&gt;"orange", "b"=&gt;"banana", "c"=&gt;"apple"); +krsort ($fruits); +reset ($fruits); +while (list ($key, $val) = each ($fruits)) { + echo "$key -&gt; $val\n"; } -</programlisting></example> + </programlisting> + </example> + </para> + <para> This example would display: - <computeroutput> + </para> + <para> + <informalexample> + <programlisting> fruits[d] = lemon fruits[c] = apple fruits[b] = banana fruits[a] = orange -</computeroutput></para> - + </programlisting> + </informalexample> + </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>, and <function>rsort</function>.</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> @@ -1593,39 +2315,57 @@ <funcprototype> <funcdef>int <function>ksort</function></funcdef> <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> </funcprototype> </funcsynopsis> - <para> Sorts an array by key, maintaining key to data correlations. This is useful mainly for associative arrays. - - <example> - <title><function>ksort</function> example</title> - <programlisting> -$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"); -ksort($fruits); -reset($fruits); -while(list($key,$val)=each($fruits)) { - echo "$key -> $val\n"; + <example> + <title><function>Ksort</function> example</title> + <programlisting role="php"> +$fruits = array ("d"=&gt;"lemon", "a"=&gt;"orange", "b"=&gt;"banana", "c"=&gt;"apple"); +ksort ($fruits); +reset ($fruits); +while (list ($key, $val) = each ($fruits)) { + echo "$key -&gt; $val\n"; } -</programlisting></example> + </programlisting> + </example> + </para> + <para> This example would display: - <computeroutput> + </para> + <para> + <informalexample> + <programlisting> fruits[a] = orange fruits[b] = banana fruits[c] = apple fruits[d] = lemon -</computeroutput></para> - + </programlisting> + </informalexample> + </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>sort</function>, and <function>rsort</function>.</simpara> - + <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> @@ -1645,30 +2385,149 @@ Like <function>array</function>, this is not really a function, but a language construct. <function>list</function> is used to assign a list of variables in one operation. - <example> - <title><function>list</function> example</title> - <programlisting> + <title><function>List</function> example</title> + <programlisting role="php"> &lt;table> &lt;tr> &lt;th>Employee name&lt;/th> &lt;th>Salary&lt;/th> &lt;/tr> + &lt;?php -$result = mysql($conn, "SELECT id, name, salary FROM employees"); -while (list($id, $name, $salary) = mysql_fetch_row($result)) { - print(" &lt;tr>\n". - " &lt;td>&lt;a href=\"info.php3?id=$id\">$name&lt;/a>&lt;/td>\n". - " &lt;td>$salary&lt;/td>\n". - " &lt;/tr>\n"); +$result = mysql_query ($conn, "SELECT id, name, salary FROM employees"); +while (list ($id, $name, $salary) = mysql_fetch_row ($result)) { + print (" &lt;tr>\n". + " &lt;td>&lt;a href=\"info.php3?id=$id\">$name&lt;/a>&lt;/td>\n". + " &lt;td>$salary&lt;/td>\n". + " &lt;/tr>\n"); } + +?> + +&lt;/table> + </programlisting> + </example> + </para> + <para> + See also <function>each</function> and <function>array</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>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>natsort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <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"> +$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> + <informalexample> + <programlisting> +Standard sorting +Array +( + [0] =&gt; img1.png + [1] =&gt; img10.png + [2] =&gt; img12.png + [3] =&gt; img2.png +) -?>&lt;/table> -</programlisting></example></para> +Natural order sorting +Array +( + [3] =&gt; img1.png + [2] =&gt; img2.png + [1] =&gt; img10.png + [0] =&gt; img12.png +) + </programlisting> + </informalexample> + For more infomation 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>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>void <function>natcasesort</function></funcdef> + <paramdef>array <parameter>array</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <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 infomation see: Martin Pool's <ulink + url="&url.strnatcmp;">Natural Order String Comparison</ulink> + page. + </para> <para> - See also: <function>each</function>, <function>array</function>.</para> + See also <function>sort</function>, + <function>natsort</function>, + <function>strnatcmp</function> and + <function>strnatcasecmp</function>. + </para> </refsect1> </refentry> @@ -1689,28 +2548,32 @@ </funcsynopsis> <para> Returns the array element in the next place that's pointed by the - internal array pointer, or false if there are no more elements.</para> + internal array pointer, or <literal>FALSE</literal> if + there are no more elements. + </para> <para> - <function>next</function> behaves like + <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. + element list, <function>next</function> returns <literal>FALSE</literal>. <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 + If the array contains empty elements, or elements that have a key + value of 0 then this function will return <literal>FALSE</literal> + 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> - + </warning> + </para> <para> See also: - <function>current</function>, <function>end</function> - <function>prev</function> and <function>reset</function></para> + <function>current</function>, <function>end</function>, + <function>prev</function>, and <function>reset</function>. + </para> </refsect1> </refentry> @@ -1728,11 +2591,13 @@ </funcprototype> </funcsynopsis> <simpara> - This is an alias for <function>current</function>.</simpara> + This is an alias for <function>current</function>. + </simpara> <para> See also: <function>end</function>, <function>next</function>, - <function>prev</function> and <function>reset</function>.</para> + <function>prev</function> and <function>reset</function>. + </para> </refsect1> </refentry> @@ -1751,27 +2616,26 @@ </funcsynopsis> <para> Returns the array element in the previous place that's pointed by - the internal array pointer, or false if there are no more + the internal array pointer, or <literal>FALSE</literal> 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> - + <warning> + <para> + If the array contains empty elements then this function will + return <literal>FALSE</literal> 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>Prev</function> behaves just like <function>next</function>, except it rewinds the internal array - pointer one place instead of advancing it.</para> - + 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> + See also: <function>current</function>, <function>end</function>, + <function>next</function>, and <function>reset</function>. + </para> </refsect1> </refentry> @@ -1792,11 +2656,13 @@ </funcprototype> </funcsynopsis> <para> - <function>range</function> returns an array of integers from + <function>Range</function> returns an array of integers from <parameter>low</parameter> to <parameter>high</parameter>, - inclusive.</para> + inclusive. + </para> <para> - See <function>shuffle</function> for an example of its use.</para> + See <function>shuffle</function> for an example of its use. + </para> </refsect1> </refentry> @@ -1816,18 +2682,18 @@ </funcprototype> </funcsynopsis> <para> - <function>reset</function> rewinds <parameter>array</parameter>'s - internal pointer to the first element.</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> + <function>Reset</function> returns the value of the first array + element. + </para> <para> - See also: - <function>current</function>, - <function>each</function>, - <function>next</function>, - <function>prev</function>, and - <function>reset</function>.</para> + See also: <function>current</function>, + <function>each</function>, <function>next</function>, + and <function>prev</function>. + </para> </refsect1> </refentry> @@ -1842,40 +2708,51 @@ <funcprototype> <funcdef>void <function>rsort</function></funcdef> <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int + <parameter><optional>sort_flags</optional></parameter> + </paramdef> </funcprototype> </funcsynopsis> <para> This function sorts an array in reverse order (highest to lowest). <example> - <title><function>rsort</function> example</title> - <programlisting> -$fruits = array("lemon","orange","banana","apple"); -rsort($fruits); -reset($fruits); -while(list($key,$val)=each($fruits)) { - echo "$key -> $val\n"; + <title><function>Rsort</function> example</title> + <programlisting role="php"> +$fruits = array ("lemon", "orange", "banana", "apple"); +rsort ($fruits); +reset ($fruits); +while (list ($key, $val) = each ($fruits)) { + echo "$key -&gt; $val\n"; } </programlisting> </example> - + </para> + <para> This example would display: - - <computeroutput> + </para> + <para> + <informalexample> + <programlisting> fruits[0] = orange fruits[1] = lemon fruits[2] = banana fruits[3] = apple - </computeroutput> - - The fruits have been sorted in reverse alphabetical order.</para> - + </programlisting> + </informalexample> + </para> <para> - See also: - <function>arsort</function>, - <function>asort</function>, - <function>ksort</function>, - <function>sort</function>, and - <function>usort</function>.</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> @@ -1894,21 +2771,25 @@ </funcsynopsis> <para> This function shuffles (randomizes the order of the elements in) - an array. + an array. You must use <function>srand</function> to seed this + function. <example> - <title><function>shuffle</function> example</title> - <programlisting> -$numbers = range(1,20); -srand(time()); -shuffle($numbers); -while (list(,$number) = each($numbers)) { + <title><function>Shuffle</function> example</title> + <programlisting role="php"> +$numbers = range (1,20); +srand ((double)microtime()*1000000); +shuffle ($numbers); +while (list (, $number) = each ($numbers)) { echo "$number "; } -</programlisting></example></para> + </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> + <function>sort</function> and <function>usort</function>. + </para> </refsect1> </refentry> @@ -1926,10 +2807,11 @@ </funcprototype> </funcsynopsis> <para> - Returns the number of elements in the array.</para> + Returns the number of elements in the array. + </para> <para> - See also: - <function>count</function></para> + See also <function>count</function>. + </para> </refsect1> </refentry> @@ -1944,36 +2826,74 @@ <funcprototype> <funcdef>void <function>sort</function></funcdef> <paramdef>array <parameter>array</parameter></paramdef> + <paramdef>int <parameter><optional>sort_flags</optional></parameter></paramdef> </funcprototype> </funcsynopsis> <para> This function sorts an array. Elements will be arranged from lowest to highest when this function has completed. <example> - <title><function>sort</function> example</title> - <programlisting> -$fruits = array("lemon","orange","banana","apple"); -sort($fruits); -reset($fruits); -while(list($key,$val)=each($fruits)) { - echo "$key -> $val\n"; + <title><function>Sort</function> example</title> + <programlisting role="php"> +&lt;?php + +$fruits = array ("lemon", "orange", "banana", "apple"); +sort ($fruits); +reset ($fruits); +while (list ($key, $val) = each ($fruits)) { + echo "fruits[".$key."] = ".$val; } -</programlisting></example> + +?&gt; + </programlisting> + </example> + </para> + <para> This example would display: - <computeroutput> + </para> + <para> + <informalexample> + <programlisting> fruits[0] = apple fruits[1] = banana fruits[2] = lemon fruits[3] = orange -</computeroutput> - The fruits have been sorted in alphabetical order.</para> + </programlisting> + </informalexample> + </para> + <para> + The fruits have been sorted in alphabetical order. + </para> <para> - See also: - <function>arsort</function>, - <function>asort</function>, - <function>ksort</function>, - <function>rsort</function>, and - <function>usort</function>.</para> + The optional second parameter <parameter>sort_flags</parameter> + may be used to modify the sorting behavior using theese valies: + </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> @@ -1999,7 +2919,21 @@ 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> + is user-defined. + </para> + <note> + <para> + Please see <function>usort</function> and + <function>uksort</function> for examples of user-defined + comparison functions. + </para> + </note> + <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> @@ -2024,39 +2958,45 @@ 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> <example> - <title><function>uksort</function> example</title> - <programlisting> -function mycompare($a, $b) { + <title><function>Uksort</function> example</title> + <programlisting role="php"> +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, mycompare); -while(list($key, $value) = each($a)) { + +$a = array (4 =&gt; "four", 3 =&gt; "three", 20 =&gt; "twenty", 10 =&gt; "ten"); + +uksort ($a, "cmp"); + +while (list ($key, $value) = each ($a)) { echo "$key: $value\n"; } -</programlisting></example> - + </programlisting> + </example> + </para> + <para> This example would display: - - <computeroutput> + </para> + <para> + <informalexample> + <programlisting> 20: twenty 10: ten 4: four 3: three - </computeroutput></para> - + </programlisting> + </informalexample> + </para> <para> - See also: - <function>arsort</function>, - <function>asort</function>, - <function>uasort</function>, - <function>ksort</function>, - <function>rsort</function>, and - <function>sort</function>.</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> @@ -2073,63 +3013,114 @@ <funcprototype> <funcdef>void <function>usort</function></funcdef> <paramdef>array <parameter>array</parameter></paramdef> - <paramdef>function <parameter>cmp_function</parameter></paramdef> + <paramdef>string <parameter>cmp_function</parameter></paramdef> </funcprototype> </funcsynopsis> <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> + 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"> -function cmp($a,$b) { + <title><function>Usort</function> example</title> + <programlisting role="php"> +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)) { + +$a = array (3, 2, 5, 6, 1); + +usort ($a, "cmp"); + +while (list ($key, $value) = each ($a)) { echo "$key: $value\n"; } -</programlisting></example> + </programlisting> + </example> + </para> + <para> This example would display: - <computeroutput> + </para> + <para> + <informalexample> + <programlisting> 0: 6 1: 5 2: 3 3: 2 4: 1 -</computeroutput> - + </programlisting> + </informalexample> + </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"> +function cmp ($a, $b) { + return strcmp($a["fruit"],$b["fruit"]); +} + +$fruits[0]["fruit"] = "lemons"; +$fruits[1]["fruit"] = "apples"; +$fruits[2]["fruit"] = "grapes"; - <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> +usort($fruits, "cmp"); +while (list ($key, $value) = each ($fruits)) { + echo "\$fruits[$key]: " . $value["fruit"] . "\n"; +} + </programlisting> + </example> + </para> <para> - See also: - <function>arsort</function>, <function>asort</function>, - <function>ksort</function>, <function>rsort</function> and - <function>sort</function>.</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> + <informalexample> + <programlisting> +$fruits[0]: apples +$fruits[1]: grapes +$fruits[2]: lemons + </programlisting> + </informalexample> + </para> + <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> + <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>
« previous php.doc (#969335407) next »