Hi,
sorry for begging again, but it's the last time, promised.
Could somebody pls. check / commit the enclosed array.xml?
changes: file complete against en-Vers. 1.68 (+10 funcs & intro), and some
transl-drafts.
Thanks,
Thomas
<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>
Erstellt ein Array
</refpurpose>
</refnamediv>
<refsect1>
<title>Beschreibung</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>array</function></funcdef>
<paramdef>mixed
<parameter><optional>...</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Gibt ein den Parametern entsprechendes Array zurück. Mit dem
<literal>=></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 => 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 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></title>
<programlisting role="php">
$fruechte = array (
"fruechte" => array ("a"=>"orange", "b"=>"banane", "c"=>"apfel"),
"zahlen" => array (1, 2, 3, 4, 5, 6),
"loecher" => array ("erstes", 5 => "zweites", "drittes")
);
</programlisting>
</example>
</para>
<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>Zählt die Werte eines Arrays</refpurpose>
</refnamediv>
<refsect1>
<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>
<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=>2, "hello"=>2, "world"=>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_diff</function></title>
<programlisting role="php">
$array1 = array ("a" => "grün", "rot", "blau");
$array2 = array ("b" => "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>
<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"=>1, "b"=>2, "c"=>3, "d"=>4, "e"=>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"=>1, "c"=>3, "e"=>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>Vertauscht Werte und Schlüssel in einem Array</refpurpose>
</refnamediv>
<refsect1>
<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>
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> Beispiel</title>
<programlisting role="php">
$trans = array_flip ($trans);
$original = strtr ($str, $trans);
</programlisting>
</example>
</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" => "grün", "rot", "blau");
$array2 = array ("b" => "grün", "gelb", "rot");
$result = array_intersect ($array1, $array2);
</programlisting>
</example>
</para>
<para>
Dies speichert <literal>array ("a" => "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>Liefert alle Schlüssel eines Arrays</refpurpose>
</refnamediv>
<refsect1>
<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>
</funcprototype>
</funcsynopsis>
<para>
<function>Array_keys</function> gibt die Schlüssel (numerisch und
String) des Arrays <parameter>input</parameter> zurück.
</para>
<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 => 100, "farbe" => "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" => array("blau", "rot", "grün"), "grösse" => 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 && $v != $term)
continue;
$t[] = $k;
}
return $t;
}
</programlisting>
</example>
</para>
</note>
<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_map</function></title>
<programlisting role="php">
function cube($n) {
return $n*$n*$n;
}
$a = array(1, 2, 3, 4, 5);
$b = array_map("cube", $a);
</programlisting>
</example>
</para>
<para>
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";
}
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>Zusammenführen von zwei oder mehr Arrays</refpurpose>
</refnamediv>
<refsect1>
<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>array
<parameter><optional>...</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<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>
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></title>
<programlisting role="php">
$array1 = array ("farbe" => "rot", 2, 4);
$array2 = array ("a", "b", "farbe" => "grün", "form" => "trapezoid", 4);
array_merge ($array1, $array2);
</programlisting>
</example>
</para>
<para>
Das resultierende Array wird <literal>array("farbe" => "grün", 2, 4,
"a", "b", "form" => "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>Rekursives Zusammenführen von zweioder mehr Arrays</refpurpose>
</refnamediv>
<refsect1>
<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>array
<parameter><optional>...</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<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>
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>
<programlisting role="php">
$ar1 = array ("color" => array ("favorite" => "red"), 5);
$ar2 = array (10, "color" => array ("favorite" => "green", "blue"));
$result = array_merge_recursive ($ar1, $ar2);
</programlisting>
</example>
</para>
<para>
Resulting array will be <literal>array ("color" => array
("favorite" => array ("red", "green"), "blue"), 5, 10)</literal>.
</para>
<para>
See also <function>array_merge</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.array-multisort">
<refnamediv>
<refname>array_multisort</refname>
<refpurpose>Sort multiple or multi-dimensional arrays</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>array_multisort</function></funcdef>
<paramdef>array <parameter>ar1</parameter></paramdef>
<paramdef>mixed
<parameter><optional>arg</optional></parameter>
</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
arrays at once or a multi-dimensional array according by one of
more dimensions. It maintains key association when sorting.
</para>
<para>
The input arrays are treated as columns of a table to be sorted
by rows - this resembles the functionality of SQL ORDER BY
clause. The first array is the primary one to sort by. The rows
(values) in that array that compare the same are sorted by the
next input array, and so on.
</para>
<para>
The argument structure of this function is a bit unusual, but
flexible. The very first argument has to be an
array. Subsequently, each argument can be either an array or a
sorting flag from the following lists.
</para>
<para>
Sorting order flags:
<itemizedlist>
<listitem>
<simpara>SORT_ASC - sort in ascending order</simpara>
</listitem>
<listitem>
<simpara>SORT_DESC - sort in descending order</simpara>
</listitem>
</itemizedlist>
</para>
<para>
Sorting type flags:
<itemizedlist>
<listitem>
<simpara>SORT_REGULAR - compare items normally</simpara>
</listitem>
<listitem>
<simpara>SORT_NUMERIC - compare items numerically</simpara>
</listitem>
<listitem>
<simpara>SORT_STRING - compare items as strings</simpara>
</listitem>
</itemizedlist>
</para>
<para>
No two sorting flags of the same type can be specified after each
array. The 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 <literal>TRUE</literal> on success, <literal>FALSE</literal>
on failure.
</para>
<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>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>array_pad</function></funcdef>
<paramdef>array <parameter>input</parameter></paramdef>
<paramdef>int <parameter>pad_size</parameter></paramdef>
<paramdef>mixed <parameter>pad_value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>Array_pad</function> returns a copy of the
<parameter>input</parameter> padded to size specified by
<parameter>pad_size</parameter> with value
<parameter>pad_value</parameter>. If
<parameter>pad_size</parameter> is positive then the array is
padded on the right, if it's negative then on the left. If the
absolute value of <parameter>pad_size</parameter> is less than or
equal to the length of the <parameter>input</parameter> then no
padding takes place.
</para>
<para>
<example>
<title><function>Array_pad</function> example</title>
<programlisting role="php">
$input = array (12, 10, 9);
$result = array_pad ($input, 5, 0);
// result is array (12, 10, 9, 0, 0)
$result = array_pad ($input, -7, -1);
// result is array (-1, -1, -1, -1, 12, 10, 9)
$result = array_pad ($input, 2, "noop");
// not padded
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.array-pop">
<refnamediv>
<refname>array_pop</refname>
<refpurpose>Pop the element off the end of array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>array_pop</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>Array_pop</function> pops and returns the last value of
the <parameter>array</parameter>, shortening the
<parameter>array</parameter> by one element.
If <parameter>array</parameter> is empty (or is not an array),
<varname>NULL</varname> will be returned.
</para>
<para>
<example>
<title><function>Array_pop</function> example</title>
<programlisting role="php">
$stack = array ("orange", "apple", "raspberry");
$fruit = array_pop ($stack);
</programlisting>
</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>.
</para>
</refsect1>
</refentry>
<refentry id="function.array-push">
<refnamediv>
<refname>array_push</refname>
<refpurpose>
Push one or more elements onto the end of array
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>array_push</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
<paramdef>mixed
<parameter><optional>...</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>Array_push</function> treats
<parameter>array</parameter> as a stack, and pushes the passed
variables onto the end of <parameter>array</parameter>. The
length of <parameter>array</parameter> increases by the number of
variables pushed. Has the same effect as:
<programlisting role="php">
$array[] = $var;
</programlisting>
repeated for each <parameter>var</parameter>.
</para>
<para>
Returns the new number of elements in the array.
</para>
<para>
<example>
<title><function>Array_push</function> example</title>
<programlisting role="php">
$stack = array (1, 2);
array_push ($stack, "+", 3);
</programlisting>
</example>
</para>
<para>
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>.
</para>
</refsect1>
</refentry>
<refentry id="function.array-rand">
<refnamediv>
<refname>array_rand</refname>
<refpurpose>
Pick one or more random entries out of an array
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>array_rand</function></funcdef>
<paramdef>array <parameter>input</parameter></paramdef>
<paramdef>int
<parameter><optional>num_req</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>Array_rand</function> is rather useful when you want to
pick one or more random entries out of an array. It takes an
<parameter>input</parameter> array and an optional argument
<parameter>num_req</parameter> which specifies how many entries you
want to pick - if not specified, it defaults to 1.
</para>
<para>
If you are picking only one entry, <function>array_rand</function>
returns the key for a random entry. Otherwise, it returns an array
of keys for the random entries. This is done so that you can pick
random keys as well as values out of the array.
</para>
<para>
Don't forget to call <function>srand</function> to seed the random
number generator.
</para>
<para>
<example>
<title><function>Array_rand</function> example</title>
<programlisting role="php">
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>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.array-reverse">
<refnamediv>
<refname>array_reverse</refname>
<refpurpose>
Return an array with elements in reverse order
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<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, preserving the keys if
<parameter>preserve_keys</parameter> is <literal>TRUE</literal>.
</para>
<para>
<example>
<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>
</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>
<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>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>array_shift</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>Array_shift</function> shifts the first value of the
<parameter>array</parameter> off and returns it, shortening the
<parameter>array</parameter> by one element and moving everything
down.
If <parameter>array</parameter> is empty (or is not an array),
<varname>NULL</varname> will be returned.
</para>
<para>
<example>
<title><function>Array_shift</function> example</title>
<programlisting role="php">
$args = array ("-v", "-f");
$opt = array_shift ($args);
</programlisting>
</example>
</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>.
</para>
</refsect1>
</refentry>
<refentry id="function.array-slice">
<refnamediv>
<refname>array_slice</refname>
<refpurpose>Extract a slice of the array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>array_slice</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
<paramdef>int <parameter>offset</parameter></paramdef>
<paramdef>int
<parameter>
<optional>length</optional>
</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<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>
<para>
If <parameter>offset</parameter> is positive, the sequence will
start at that offset in the <parameter>array</parameter>. If
<parameter>offset</parameter> is negative, the sequence will
start that far from the end of the <parameter>array</parameter>.
</para>
<para>
If <parameter>length</parameter> is given and is positive, then
the sequence will have that many elements in it. If
<parameter>length</parameter> is given and is negative then the
sequence will stop that many elements from the end of the
array. If it is omitted, then the sequence will have everything
from <parameter>offset</parameter> up until the end of the
<parameter>array</parameter>.
</para>
<para>
<example>
<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"
</programlisting>
</example>
</para>
<para>
See also <function>array_splice</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.array-splice">
<refnamediv>
<refname>array_splice</refname>
<refpurpose>
Remove a portion of the array and replace it with something
else
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>array_splice</function></funcdef>
<paramdef>array <parameter>input</parameter></paramdef>
<paramdef>int <parameter>offset</parameter></paramdef>
<paramdef>int
<parameter><optional>length</optional></parameter>
</paramdef>
<paramdef>array
<parameter>
<optional>replacement</optional>
</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>Array_splice</function> removes the elements designated
by <parameter>offset</parameter> and
<parameter>length</parameter> from the
<parameter>input</parameter> array, and replaces them with the
elements of the <parameter>replacement</parameter> array, if
supplied.
</para>
<para>
If <parameter>offset</parameter> is positive then the start of
removed portion is at that offset from the beginning of the
<parameter>input</parameter> array. If
<parameter>offset</parameter> is negative then it starts that far
from the end of the <parameter>input</parameter> array.
</para>
<para>
If <parameter>length</parameter> is omitted, removes everything
from <parameter>offset</parameter> to the end of the array. If
<parameter>length</parameter> is specified and is positive, then
that many elements will be removed. If
<parameter>length</parameter> is specified and is negative then
the end of the removed portion will be that many elements from
the end of the array. Tip: to remove everything from
<parameter>offset</parameter> to the end of the array when
<parameter>replacement</parameter> is also specified, use
<literal>count($input)</literal> for
<parameter>length</parameter>.
</para>
<para>
If <parameter>replacement</parameter> array is specified, then
the removed elements are replaced with elements from this array.
If <parameter>offset</parameter> and
<parameter>length</parameter> are such that nothing is removed,
then the elements from the <parameter>replacement</parameter>
array are inserted in the place specified by the
<parameter>offset</parameter>. Tip: if the replacement is just
one element it is not necessary to put <literal>array()</literal>
around it, unless the element is an array itself.
</para>
<para>
The following equivalences hold:
<programlisting>
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>
<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_unique</function> example</title>
<programlisting role="php">
$input = array ("a" => "green", "red", "b" => "green", "blue", "red");
$result = array_unique ($input);
</programlisting>
</example>
</para>
<para>
This makes <varname>$result</varname> have <literal>array ("a" =>
"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>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>array_unshift</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
<paramdef>mixed
<parameter>
<optional>...</optional>
</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>Array_unshift</function> prepends passed elements to
the front of the <parameter>array</parameter>. Note that the list
of elements is prepended as a whole, so that the prepended
elements stay in the same order.
</para>
<para>
Returns the new number of elements in the
<parameter>array</parameter>.
</para>
<para>
<example>
<title><function>Array_unshift</function> example</title>
<programlisting role="php">
$queue = array ("p1", "p3");
array_unshift ($queue, "p4", "p5", "p6");
</programlisting>
</example>
</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>.
</para>
</refsect1>
</refentry>
<refentry id="function.array-values">
<refnamediv>
<refname>array_values</refname>
<refpurpose>Return all the values of an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>array_values</function></funcdef>
<paramdef>array <parameter>input</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>array_values</function> returns all the values from the
<parameter>input</parameter> array.
</para>
<para>
<example>
<title><function>Array_values</function> example</title>
<programlisting role="php">
$array = array ("size" => "XL", "color" => "gold");
array_values ($array); // returns array ("XL", "gold")
</programlisting>
</example>
</para>
<note>
<para>
This function was added to PHP 4, below is an implementation for
those still using PHP 3.
<example>
<title>
Implementation of <function>array_values</function> for PHP 3
users
</title>
<programlisting role="php">
function array_values ($arr) {
$t = array();
while (list($k, $v) = each ($arr)) {
$t[] = $v;
}
return $t;
}
</programlisting>
</example>
</para>
</note>
</refsect1>
</refentry>
<refentry id="function.array-walk">
<refnamediv>
<refname>array_walk</refname>
<refpurpose>
Apply a user function to every member of an array
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>array_walk</function></funcdef>
<paramdef>array <parameter>arr</parameter></paramdef>
<paramdef>string <parameter>func</parameter></paramdef>
<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.
</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>
<note>
<para>
If <parameter>func</parameter> needs to be working with the
actual values of the array, specify that the first parameter of
<parameter>func</parameter> should be passed by reference. Then
any changes made to those elements will be made in the array
itself.
</para>
</note>
<note>
<para>
Passing the key and userdata to <parameter>func</parameter> was
added in 4.0.
</para>
<para>
In PHP 4 <function>reset</function> needs to be called as
necessary since <function>array_walk</function> does not reset
the array by default.
</para>
</note>
<para>
<example>
<title><function>Array_walk</function> example</title>
<programlisting role="php">
$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple");
function test_alter (&$item1, $key, $prefix) {
$item1 = "$prefix: $item1";
}
function test_print ($item2, $key) {
echo "$key. $item2<br>\n";
}
array_walk ($fruits, 'test_print');
reset ($fruits);
array_walk ($fruits, 'test_alter', 'fruit');
reset ($fruits);
array_walk ($fruits, 'test_print');
</programlisting>
</example>
</para>
<simpara>
See also <function>each</function> and <function>list</function>.
</simpara>
</refsect1>
</refentry>
<refentry id="function.arsort">
<refnamediv>
<refname>arsort</refname>
<refpurpose>
Sort an array in reverse order and maintain index association
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<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>
This function sorts an array such that array indices maintain
their correlation with the array elements they are associated
with. This is used mainly when sorting associative arrays where
the actual element order is significant.
<example>
<title><function>Arsort</function> example</title>
<programlisting role="php">
$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple");
arsort ($fruits);
reset ($fruits);
while (list ($key, $val) = each ($fruits)) {
echo "$key = $val\n";
}
</programlisting>
</example>
</para>
<para>
This example would display:
</para>
<para>
<informalexample>
<programlisting>
fruits[a] = orange
fruits[d] = lemon
fruits[b] = banana
fruits[c] = apple
</programlisting>
</informalexample>
</para>
<para>
The fruits have been sorted in reverse alphabetical order, and
the index associated with each element has been maintained.
</para>
<para>
You may modify the behavior of the sort using the optional
parameter <parameter>sort_flags</parameter>, for details
see <function>sort</function>.
</para>
<para>
See also: <function>asort</function>, <function>rsort</function>,
<function>ksort</function>, and <function>sort</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.asort">
<refnamediv>
<refname>asort</refname>
<refpurpose>Sort an array and maintain index association</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<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>
This function sorts an array such that array indices maintain
their correlation with the array elements they are associated
with. This is used mainly when sorting associative arrays where
the actual element order is significant.
<example>
<title><function>Asort</function> example</title>
<programlisting role="php">
$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple");
asort ($fruits);
reset ($fruits);
while (list ($key, $val) = each ($fruits)) {
echo "$key = $val\n";
}
</programlisting>
</example>
</para>
<para>
This example would display:
</para>
<para>
<informalexample>
<programlisting>
fruits[c] = apple
fruits[b] = banana
fruits[d] = lemon
fruits[a] = orange
</programlisting>
</informalexample>
</para>
<para>
The fruits have been sorted in alphabetical order, and the index
associated with each element has been maintained.
</para>
<para>
You may modify the behavior of the sort using the optional
parameter <parameter>sort_flags</parameter>, for details
see <function>sort</function>.
</para>
<para>
See also <function>arsort</function>, <function>rsort</function>,
<function>ksort</function>, and <function>sort</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.compact">
<refnamediv>
<refname>compact</refname>
<refpurpose>
Create array containing variables and their values
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>compact</function></funcdef>
<paramdef>mixed <parameter>varname</parameter></paramdef>
<paramdef>mixed
<parameter><optional>...</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>Compact</function> takes a variable number of
parameters. Each parameter can be either a string containing the
name of the variable, or an array of variable names. The array
can contain other arrays of variable names inside it;
<function>compact</function> handles it recursively.
</para>
<para>
For each of these, <function>compact</function> looks for a
variable with that name in the current symbol table and adds it
to the output array such that the variable name becomes the key
and the contents of the variable become the value for that key.
In short, it does the opposite of <function>extract</function>.
It returns the output array with all the variables added to it.
</para>
<para>
Any strings that are not set will simply be skipped.
</para>
<para>
<example>
<title><function>Compact</function> example</title>
<programlisting role="php">
$city = "San Francisco";
$state = "CA";
$event = "SIGGRAPH";
$location_vars = array ("city", "state");
$result = compact ("event", "nothing_here", $location_vars);
</programlisting>
<para>
After this, <varname>$result</varname> will be <literal>array ("event"
=> "SIGGRAPH", "city" => "San Francisco", "state" => "CA")</literal>.
</para>
</example>
</para>
<para>
See also <function>extract</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.count">
<refnamediv>
<refname>count</refname>
<refpurpose>Count elements in a variable</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>count</function></funcdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns the number of elements in <parameter>var</parameter>,
which is typically an array (since anything else will have one
element).
</para>
<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>
<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>
<refentry id="function.current">
<refnamediv>
<refname>current</refname>
<refpurpose>Return the current element in an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>current</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Every array has an internal pointer to its "current" element,
which is initialized to the first element inserted into the
array.
</para>
<para>
The <function>current</function> function simply returns the
array element that's currently being pointed by the internal
pointer. It does not move the pointer in any way. If the
internal pointer points beyond the end of the elements list,
<function>current</function> returns <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>
</refsect1>
</refentry>
<refentry id="function.each">
<refnamediv>
<refname>each</refname>
<refpurpose>
Return the next key and value pair from an array
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>each</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns the current key and value pair from the array
<parameter>array</parameter> and advances the array cursor. This
pair is returned in a four-element array, with the keys
<emphasis>0</emphasis>, <emphasis>1</emphasis>,
<emphasis>key</emphasis>, and
<emphasis>value</emphasis>. Elements <emphasis>0</emphasis> and
<emphasis>key</emphasis> contain the key name of the array
element, and <emphasis>1</emphasis> and
<emphasis>value</emphasis> contain the data.
</para>
<para>
If the internal pointer for the array points past the end of the
array contents, <function>each</function> returns
<literal>FALSE</literal>.
</para>
<para>
<example>
<title><function>Each</function> examples</title>
<programlisting role="php">
$foo = array ("bob", "fred", "jussi", "jouni", "egon", "marliese");
$bar = each ($foo);
</programlisting>
<para>
<varname>$bar</varname> now contains the following key/value
pairs:
<itemizedlist spacing="compact">
<listitem><simpara>0 => 0</simpara></listitem>
<listitem><simpara>1 => 'bob'</simpara></listitem>
<listitem><simpara>key => 0</simpara></listitem>
<listitem><simpara>value => 'bob'</simpara></listitem>
</itemizedlist>
<programlisting role="php">
$foo = array ("Robert" => "Bob", "Seppo" => "Sepi");
$bar = each ($foo);
</programlisting>
</para>
<para>
<varname>$bar</varname> now contains the following key/value
pairs:
<itemizedlist spacing="compact">
<listitem><simpara>0 => '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>
<para>
<function>Each</function> is typically used in conjunction with
<function>list</function> to traverse an array; for instance,
<varname>$HTTP_POST_VARS</varname>:
<example>
<title>
Traversing <varname>$HTTP_POST_VARS</varname> with
<function>each</function>
</title>
<programlisting role="php">
echo "Values submitted via POST method:<br>";
reset ($HTTP_POST_VARS);
while (list ($key, $val) = each ($HTTP_POST_VARS)) {
echo "$key => $val<br>";
}
</programlisting>
</example>
</para>
<para>
After <function>each</function> has executed, the array cursor
will be left on the next element of the array, or on the last
element if it hits the end of the array.
</para>
<para>
See also <function>key</function>, <function>list</function>,
<function>current</function>, <function>reset</function>,
<function>next</function>, and <function>prev</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.end">
<refnamediv>
<refname>end</refname>
<refpurpose>
Set the internal pointer of an array to its last element
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<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, 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>
</refsect1>
</refentry>
<refentry id="function.extract">
<refnamediv>
<refname>extract</refname>
<refpurpose>
Import variables into the symbol table from an array
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>extract</function></funcdef>
<paramdef>array <parameter>var_array</parameter></paramdef>
<paramdef>int
<parameter><optional>extract_type</optional></parameter>
</paramdef>
<paramdef>string
<parameter><optional>prefix</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
This function is used to import variables from an array into the
current symbol table. It takes associative array
<parameter>var_array</parameter> and treats keys as variable
names and values as variable values. For each key/value pair it
will create a variable in the current symbol table, subject to
<parameter>extract_type</parameter> and
<parameter>prefix</parameter> parameters.
</para>
<note>
<para>
Since version 4.0.5 this function returns the number of
variables extracted.
</para>
</note>
<para>
<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>
</listitem>
</varlistentry>
<varlistentry>
<term>EXTR_SKIP</term>
<listitem>
<simpara>
If there is a collision, don't overwrite the existing
variable.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>EXTR_PREFIX_SAME</term>
<listitem>
<simpara>If there is a collision, prefix the variable name with
<parameter>prefix</parameter>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>EXTR_PREFIX_ALL</term>
<listitem>
<simpara>
Prefix all variable names with <parameter>prefix</parameter>. Since PHP
4.0.5 this includes numeric ones as well.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>EXTR_PREFIX_INVALID</term>
<listitem>
<simpara>
Only prefix invalid/numeric variable names with
<parameter>prefix</parameter>. This flag has been added in PHP 4.0.5.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
If <parameter>extract_type</parameter> is not specified, it is
assumed to be EXTR_OVERWRITE.
</para>
<para>
Note that <parameter>prefix</parameter> is only required if
<parameter>extract_type</parameter> is EXTR_PREFIX_SAME, EXTR_PREFIX_ALL,
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> 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>
<para>
<example>
<title><function>Extract</function> example</title>
<programlisting role="php">
<?php
/* Suppose that $var_array is an array returned from
wddx_deserialize */
$size = "large";
$var_array = array ("color" => "blue",
"size" => "medium",
"shape" => "sphere");
extract ($var_array, EXTR_PREFIX_SAME, "wddx");
print "$color, $size, $shape, $wddx_size\n";
?>
</programlisting>
</example>
</para>
<para>
The above example will produce:
<programlisting>
blue, large, sphere, medium
</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>
See also: <function>compact</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.in-array">
<refnamediv>
<refname>in_array</refname>
<refpurpose>Return TRUE if a value exists in an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>in_array</function></funcdef>
<paramdef>mixed <parameter>needle</parameter></paramdef>
<paramdef>array <parameter>haystack</parameter></paramdef>
<paramdef>bool
<parameter><optional>strict</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Searches <parameter>haystack</parameter> for
<parameter>needle</parameter> and returns <literal>TRUE</literal>
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>in_array</function>
will also check the types of the <parameter>needle</parameter>
in the <parameter>haystack</parameter>.
</para>
<para>
<example>
<title><function>In_array</function> example</title>
<programlisting role="php">
$os = array ("Mac", "NT", "Irix", "Linux");
if (in_array ("Irix", $os)){
print "Got Irix";
}
</programlisting>
</example>
</para>
<para>
<example>
<title><function>In_array</function> with strict example</title>
<programlisting role="php">
<?php
$a = array('1.10', 12.4, 1.13);
if (in_array('12.4', $a, TRUE))
echo "'12.4' found with strict check\n";
if (in_array(1.13, $a, TRUE))
echo "1.13 found with strict check\n";
?>
// This will output:
1.13 found with strict check
</programlisting>
</example>
</para>
<para>
See also <function>array_search</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.array-search">
<refnamediv>
<refname>array_search</refname>
<refpurpose>
Searches the array for a given value and returns the corresponding key if successful
</refpurpose>
</refnamediv>
<refsect1>
<title>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>
<refpurpose>Fetch a key from an associative array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>key</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>Key</function> returns the index element of the
current array position.
</para>
<para>
See also <function>current</function> and <function>next</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.krsort">
<refnamediv>
<refname>krsort</refname>
<refpurpose>Sort an array by key in reverse order</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<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 role="php">
$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple");
krsort ($fruits);
reset ($fruits);
while (list ($key, $val) = each ($fruits)) {
echo "$key -> $val\n";
}
</programlisting>
</example>
</para>
<para>
This example would display:
</para>
<para>
<informalexample>
<programlisting>
fruits[d] = lemon
fruits[c] = apple
fruits[b] = banana
fruits[a] = orange
</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>,
<function>natsort</function>and <function>rsort</function>.
</simpara>
</refsect1>
</refentry>
<refentry id="function.ksort">
<refnamediv>
<refname>ksort</refname>
<refpurpose>Sort an array by key</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<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 role="php">
$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple");
ksort ($fruits);
reset ($fruits);
while (list ($key, $val) = each ($fruits)) {
echo "$key -> $val\n";
}
</programlisting>
</example>
</para>
<para>
This example would display:
</para>
<para>
<informalexample>
<programlisting>
fruits[a] = orange
fruits[b] = banana
fruits[c] = apple
fruits[d] = lemon
</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>, <function>natsort</function>, and
<function>rsort</function>.
</simpara>
<note>
<para>
The second parameter was added in PHP 4.
</para>
</note>
</refsect1>
</refentry>
<refentry id="function.list">
<refnamediv>
<refname>list</refname>
<refpurpose>
Assign variables as if they were an array
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>list</function></funcdef>
<varargs/>
</funcprototype>
</funcsynopsis>
<para>
Like <function>array</function>, this is not really a function,
but a language construct. <function>list</function> is used to
assign a list of variables in one operation.
<example>
<title><function>List</function> example</title>
<programlisting role="php">
<table>
<tr>
<th>Employee name</th>
<th>Salary</th>
</tr>
<?php
$result = mysql_query ($conn, "SELECT id, name, salary FROM employees");
while (list ($id, $name, $salary) = mysql_fetch_row ($result)) {
print (" <tr>\n".
" <td><a href=\"info.php3?id=$id\">$name</a></td>\n".
" <td>$salary</td>\n".
" </tr>\n");
}
?>
</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] => img1.png
[1] => img10.png
[2] => img12.png
[3] => img2.png
)
Natural order sorting
Array
(
[3] => img1.png
[2] => img2.png
[1] => img10.png
[0] => img12.png
)
</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>sort</function>,
<function>natsort</function>,
<function>strnatcmp</function> and
<function>strnatcasecmp</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.next">
<refnamediv>
<refname>next</refname>
<refpurpose>
Advance the internal array pointer of an array
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>next</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns the array element in the next place that's pointed by the
internal array pointer, or <literal>FALSE</literal> if
there are no more elements.
</para>
<para>
<function>Next</function> behaves like
<function>current</function>, with one difference. It advances
the internal array pointer one place forward before returning the
element. That means it returns the next array element and
advances the internal array pointer by one. If advancing the
internal array pointer results in going beyond the end of the
element list, <function>next</function> returns <literal>FALSE</literal>.
<warning>
<para>
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>
<para>
See also:
<function>current</function>, <function>end</function>,
<function>prev</function>, and <function>reset</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pos">
<refnamediv>
<refname>pos</refname>
<refpurpose>Get the current element from an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>pos</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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>
</refsect1>
</refentry>
<refentry id="function.prev">
<refnamediv>
<refname>prev</refname>
<refpurpose>Rewind the internal array pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>prev</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns the array element in the previous place that's pointed by
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 <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>next</function>, except it rewinds the internal array
pointer one place instead of advancing it.
</para>
<para>
See also: <function>current</function>, <function>end</function>,
<function>next</function>, and <function>reset</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.range">
<refnamediv>
<refname>range</refname>
<refpurpose>
Create an array containing a range of integers
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>range</function></funcdef>
<paramdef>int <parameter>low</parameter></paramdef>
<paramdef>int <parameter>high</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>Range</function> returns an array of integers from
<parameter>low</parameter> to <parameter>high</parameter>,
inclusive.
</para>
<para>
See <function>shuffle</function> for an example of its use.
</para>
</refsect1>
</refentry>
<refentry id="function.reset">
<refnamediv>
<refname>reset</refname>
<refpurpose>
Set the internal pointer of an array to its first element
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>reset</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>Reset</function> rewinds <parameter>array</parameter>'s
internal pointer to the first element.
</para>
<para>
<function>Reset</function> returns the value of the first array
element.
</para>
<para>
See also: <function>current</function>,
<function>each</function>, <function>next</function>,
and <function>prev</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.rsort">
<refnamediv>
<refname>rsort</refname>
<refpurpose>Sort an array in reverse order</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<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 role="php">
$fruits = array ("lemon", "orange", "banana", "apple");
rsort ($fruits);
reset ($fruits);
while (list ($key, $val) = each ($fruits)) {
echo "$key -> $val\n";
}
</programlisting>
</example>
</para>
<para>
This example would display:
</para>
<para>
<informalexample>
<programlisting>
fruits[0] = orange
fruits[1] = lemon
fruits[2] = banana
fruits[3] = apple
</programlisting>
</informalexample>
</para>
<para>
The fruits have been sorted in reverse alphabetical order.
</para>
<para>
You may modify the behavior of the sort using the optional
parameter <parameter>sort_flags</parameter>, for details
see <function>sort</function>.
</para>
<para>
See also: <function>arsort</function>,
<function>asort</function>, <function>ksort</function>,
<function>sort</function>, and <function>usort</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.shuffle">
<refnamediv>
<refname>shuffle</refname>
<refpurpose>Shuffle an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>shuffle</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
This function shuffles (randomizes the order of the elements in)
an array. You must use <function>srand</function> to seed this
function.
<example>
<title><function>Shuffle</function> example</title>
<programlisting role="php">
$numbers = range (1,20);
srand ((double)microtime()*1000000);
shuffle ($numbers);
while (list (, $number) = each ($numbers)) {
echo "$number ";
}
</programlisting>
</example>
</para>
<para>
See also <function>arsort</function>, <function>asort</function>,
<function>ksort</function>, <function>rsort</function>,
<function>sort</function> and <function>usort</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.sizeof">
<refnamediv>
<refname>sizeof</refname>
<refpurpose>Get the number of elements in an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>sizeof</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns the number of elements in the array.
</para>
<para>
See also <function>count</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.sort">
<refnamediv>
<refname>sort</refname>
<refpurpose>Sort an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<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 role="php">
<?php
$fruits = array ("lemon", "orange", "banana", "apple");
sort ($fruits);
reset ($fruits);
while (list ($key, $val) = each ($fruits)) {
echo "fruits[".$key."] = ".$val;
}
?>
</programlisting>
</example>
</para>
<para>
This example would display:
</para>
<para>
<informalexample>
<programlisting>
fruits[0] = apple
fruits[1] = banana
fruits[2] = lemon
fruits[3] = orange
</programlisting>
</informalexample>
</para>
<para>
The fruits have been sorted in alphabetical order.
</para>
<para>
The optional second parameter <parameter>sort_flags</parameter>
may be used to modify the sorting behavior using 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>
<refentry id="function.uasort">
<refnamediv>
<refname>uasort</refname>
<refpurpose>
Sort an array with a user-defined comparison function and
maintain index association
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>uasort</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
<paramdef>function <parameter>cmp_function</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
This function sorts an array such that array indices maintain
their correlation with the array elements they are associated
with. This is used mainly when sorting associative arrays where
the actual element order is significant. The comparison function
is user-defined.
</para>
<note>
<para>
Please see <function>usort</function> and
<function>uksort</function> for examples of user-defined
comparison functions.
</para>
</note>
<para>
See also: <function>usort</function>, <function>uksort</function>,
<function>sort</function>, <function>asort</function>,
<function>arsort</function>, <function>ksort</function>
and <function>rsort</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.uksort">
<refnamediv>
<refname>uksort</refname>
<refpurpose>
Sort an array by keys using a user-defined comparison function
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>uksort</function></funcdef>
<paramdef>array <parameter>array</parameter></paramdef>
<paramdef>function <parameter>cmp_function</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
This function will sort the keys of an array using a
user-supplied comparison function. If the array you wish to sort
needs to be sorted by some non-trivial criteria, you should use
this function.
</para>
<para>
<example>
<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, "cmp");
while (list ($key, $value) = each ($a)) {
echo "$key: $value\n";
}
</programlisting>
</example>
</para>
<para>
This example would display:
</para>
<para>
<informalexample>
<programlisting>
20: twenty
10: ten
4: four
3: three
</programlisting>
</informalexample>
</para>
<para>
See also: <function>usort</function>, <function>uasort</function>,
<function>sort</function>, <function>asort</function>,
<function>arsort</function>, <function>ksort</function>,
<function>natsort</function> and <function>rsort</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.usort">
<refnamediv>
<refname>usort</refname>
<refpurpose>
Sort an array by values using a user-defined comparison function
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>usort</function></funcdef>
<paramdef>array <parameter>array</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>
<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) {
if ($a == $b) return 0;
return ($a > $b) ? -1 : 1;
}
$a = array (3, 2, 5, 6, 1);
usort ($a, "cmp");
while (list ($key, $value) = each ($a)) {
echo "$key: $value\n";
}
</programlisting>
</example>
</para>
<para>
This example would display:
</para>
<para>
<informalexample>
<programlisting>
0: 6
1: 5
2: 3
3: 2
4: 1
</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";
usort($fruits, "cmp");
while (list ($key, $value) = each ($fruits)) {
echo "\$fruits[$key]: " . $value["fruit"] . "\n";
}
</programlisting>
</example>
</para>
<para>
When sorting a multi-dimensional array, $a and $b contain
references to the first index of the array.
</para>
<para>
This example would display:
</para>
<para>
<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>
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
