mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
3009540bdc
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@11942 c90b9560-bf6c-de11-be94-00142212c4b1
1549 lines
48 KiB
Text
1549 lines
48 KiB
Text
<reference id="ref.array">
|
|
<title>Array functions</title>
|
|
<titleabbrev>Arrays</titleabbrev>
|
|
|
|
<refentry id="function.array">
|
|
<refnamediv>
|
|
<refname>array</refname>
|
|
<refpurpose>
|
|
Create an array
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>array <function>array</function></funcdef>
|
|
<varargs>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns an array of the parameters. The parameters can be given
|
|
an index with the <literal>=></literal> operator.
|
|
|
|
<note>
|
|
<para>
|
|
<function>array</function> is a language construct used to represent
|
|
literal arrays, and not a regular function.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
The following example demonstrates how to create a
|
|
two-dimensional array, how to specify keys for associative
|
|
arrays, and how to skip-and-continue numeric indices in normal
|
|
arrays.
|
|
|
|
<example>
|
|
<title><function>array</function> example</title>
|
|
<programlisting>
|
|
$fruits = array(
|
|
"fruits" => array("a"=>"orange","b"=>"banana","c"=>"apple"),
|
|
"numbers" => array(1, 2, 3, 4, 5, 6),
|
|
"holes" => array("first", 5 => "second", "third")
|
|
);
|
|
</programlisting></example>
|
|
|
|
<para>
|
|
See also:
|
|
<function>list</function>.
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-push">
|
|
<refnamediv>
|
|
<refname>array_push</refname>
|
|
<refpurpose>Push one or more elements onto the end of array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<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>
|
|
</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>
|
|
$array[] = $var;
|
|
</programlisting>
|
|
repeated for each <parameter>var</parameter>.
|
|
|
|
<para>
|
|
Returns the new number of elements in the array.
|
|
|
|
<para>
|
|
<example>
|
|
<title><function>array_push</function> example</title>
|
|
<programlisting>
|
|
$stack = array(1, 2);
|
|
array_push($stack, "+", 3);
|
|
</programlisting>
|
|
</example>
|
|
This example would result in $stack having 4 elements: 1, 2, "+", and 3.
|
|
|
|
<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.
|
|
</note>
|
|
</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>
|
|
<funcdef>mixed <function>array_pop</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</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.
|
|
|
|
<para>
|
|
<example>
|
|
<title><function>array_pop</function> example</title>
|
|
<programlisting>
|
|
$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".
|
|
</example>
|
|
|
|
<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.
|
|
</note>
|
|
</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><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>
|
|
Returns the new number of elements in the
|
|
<parameter>array</parameter>.
|
|
|
|
<para>
|
|
<example>
|
|
<title><function>array_unshift</function> example</title>
|
|
<programlisting>
|
|
$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>
|
|
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.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-shift">
|
|
<refnamediv>
|
|
<refname>array_shift</refname>
|
|
<refpurpose>Pop an element of the beginning of array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>mixed <function>array_shift</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</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.
|
|
|
|
<para>
|
|
<example>
|
|
<title><function>array_shift</function> example</title>
|
|
<programlisting>
|
|
$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>
|
|
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.
|
|
</note>
|
|
</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>
|
|
<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>
|
|
</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>
|
|
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>
|
|
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>
|
|
<example>
|
|
<title><function>array_slice</function> examples</title>
|
|
<programlisting>
|
|
$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>
|
|
See also <function>array_splice</function>.
|
|
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</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>
|
|
<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>
|
|
</funcsynopsis>
|
|
|
|
<para>
|
|
<function>array_splice</function> removed 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>
|
|
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>
|
|
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>
|
|
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>
|
|
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>
|
|
Returns the array consisting of removed elements.
|
|
|
|
<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")
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
See also <function>array_slice</function>.
|
|
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-merge">
|
|
<refnamediv>
|
|
<refname>array_merge</refname>
|
|
<refpurpose>Merge two or more arrays</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<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>
|
|
</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>
|
|
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>
|
|
<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);
|
|
</programlisting>
|
|
<para>
|
|
Resulting array will be array("color" => "green", 2, 4, "a", "b", "shape" => "trapezoid").
|
|
</example>
|
|
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-keys">
|
|
<refnamediv>
|
|
<refname>array_keys</refname>
|
|
<refpurpose>Return all the keys of an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>array <function>array_keys</function></funcdef>
|
|
<paramdef>array <parameter>input</parameter></paramdef>
|
|
</funcsynopsis>
|
|
|
|
<para>
|
|
<function>array_keys</function> returns all the keys, numeric and string, from the <parameter>input</parameter> array.
|
|
|
|
<para>
|
|
<example>
|
|
<title><function>array_keys</function> example</title>
|
|
<programlisting>
|
|
$array = array(0 => 100, "color" => "red");
|
|
array_keys($array); // returns array(0, "color")
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
See also <function>array_values</function>.
|
|
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</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>
|
|
<funcdef>array <function>array_values</function></funcdef>
|
|
<paramdef>array <parameter>input</parameter></paramdef>
|
|
</funcsynopsis>
|
|
|
|
<para>
|
|
<function>array_values</function> returns all the values from the <parameter>input</parameter> array.
|
|
|
|
<para>
|
|
<example>
|
|
<title><function>array_values</function> example</title>
|
|
<programlisting>
|
|
$array = array("size" => "XL", "color" => "gold");
|
|
array_values($array); // returns array("XL", "gold")
|
|
</programlisting>
|
|
</example>
|
|
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</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>
|
|
<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>
|
|
</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.
|
|
|
|
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>.
|
|
|
|
<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>
|
|
|
|
<para>
|
|
<example>
|
|
<title><function>array_walk</function> example</title>
|
|
<programlisting>
|
|
$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' );
|
|
array_walk( $fruits, 'test_alter', 'fruit' );
|
|
array_walk( $fruits, 'test_print' );
|
|
</programlisting>
|
|
</example>
|
|
|
|
<simpara>
|
|
See also <function>each</function> and <function>list</function>.
|
|
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.arsort">
|
|
<refnamediv>
|
|
<refname>arsort</refname>
|
|
<refpurpose>
|
|
Sort an array in reverse order and maintain index association
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>void <function>arsort</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function sorts an array such that array indices maintain their
|
|
correlation with the array elements they are associated with. This is
|
|
used mainly when sorting associative arrays where the actual element
|
|
order is significant.
|
|
<example>
|
|
<title><function>arsort</function> example</title>
|
|
<programlisting>
|
|
$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple");
|
|
arsort($fruits);
|
|
for(reset($fruits); $key = key($fruits); next($fruits)) {
|
|
echo "fruits[$key] = ".$fruits[$key]."\n";
|
|
}
|
|
</programlisting></example>
|
|
This example would display:
|
|
<computeroutput>
|
|
fruits[a] = orange
|
|
fruits[d] = lemon
|
|
fruits[b] = banana
|
|
fruits[c] = apple
|
|
</computeroutput>
|
|
The fruits have been sorted in reverse alphabetical order, and
|
|
the index associated with each element has been maintained.
|
|
<para>
|
|
See also: <function>asort</function>, <function>rsort</function>,
|
|
<function>ksort</function>, and <function>sort</function>.
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.asort">
|
|
<refnamediv>
|
|
<refname>asort</refname>
|
|
<refpurpose>Sort an array and maintain index association</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>void <function>asort</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function sorts an array such that array indices maintain their
|
|
correlation with the array elements they are associated with. This is
|
|
used mainly when sorting associative arrays where the actual element
|
|
order is significant.
|
|
<example>
|
|
<title><function>asort</function> example</title>
|
|
<programlisting>
|
|
$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple");
|
|
asort($fruits);
|
|
for(reset($fruits); $key = key($fruits); next($fruits)) {
|
|
echo "fruits[$key] = ".$fruits[$key]."\n";
|
|
}
|
|
</programlisting></example>
|
|
This example would display:
|
|
<computeroutput>
|
|
fruits[c] = apple
|
|
fruits[b] = banana
|
|
fruits[d] = lemon
|
|
fruits[a] = orange
|
|
</computeroutput>
|
|
The fruits have been sorted in alphabetical order, and the index
|
|
associated with each element has been maintained.
|
|
<para>
|
|
See also <function>arsort</function>, <function>rsort</function>,
|
|
<function>ksort</function>, and <function>sort</function>.
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.compact">
|
|
<refnamediv>
|
|
<refname>compact</refname>
|
|
<refpurpose>Create array containing variables and their values</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>array <function>compact</function></funcdef>
|
|
<paramdef><parameter>string varname | array
|
|
varnames</parameter></paramdef>
|
|
<paramdef><parameter><optional>...</optional></parameter></paramdef>
|
|
</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>
|
|
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>
|
|
<example>
|
|
<title><function>compact</function> example</title>
|
|
<programlisting>
|
|
$city = "San Francisco";
|
|
$state = "CA";
|
|
$event = "SIGGRAPH";
|
|
|
|
$location_vars = array("city", "state");
|
|
|
|
$result = compact("event", $location_vars);
|
|
</programlisting>
|
|
|
|
<para>
|
|
After this, $result will be array("event" => "SIGGRAPH", "city" => "San Francisco", "state" => "CA").
|
|
</example>
|
|
|
|
<para>
|
|
See also <function>extract</function>.
|
|
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.count">
|
|
<refnamediv>
|
|
<refname>count</refname>
|
|
<refpurpose>count elements in a variable</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>int <function>count</function></funcdef>
|
|
<paramdef>mixed <parameter>var</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns the number of elements in <parameter>var</parameter>, which is
|
|
typically an array (since anything else will have one element).
|
|
<para>
|
|
Returns 1 if the variable is not an array.
|
|
<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>
|
|
See also:
|
|
<function>sizeof</function>, <function>isset</function>, and
|
|
<function>is_array</function>.
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.current">
|
|
<refnamediv>
|
|
<refname>current</refname>
|
|
<refpurpose>Return the current element in an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>mixed <function>current</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
Every array has an internal pointer to its "current" element,
|
|
which is initialized to the first element inserted into the
|
|
array.
|
|
|
|
<para>
|
|
The <function>current</function> function simply returns the
|
|
array element that's currently being pointed by the internal
|
|
pointer. It does not move the pointer in any way. If the
|
|
internal pointer points beyond the end of the elements list,
|
|
<function>current</function> returns false.
|
|
|
|
<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.
|
|
</warning>
|
|
|
|
<para>
|
|
See also:
|
|
<function>end</function>, <function>next</function>,
|
|
<function>prev</function> and <function>reset</function>.
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.each">
|
|
<refnamediv>
|
|
<refname>each</refname>
|
|
<refpurpose>Return the next key and value pair from an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>array <function>each</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns the current key 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>
|
|
If the internal pointer for the array points past the end of the
|
|
array contents, <function>each</function> returns false.
|
|
|
|
<para>
|
|
<example>
|
|
<title><function>each</function> examples</title>
|
|
<programlisting>
|
|
$foo = array( "bob", "fred", "jussi", "jouni" );
|
|
$bar = each( $foo );
|
|
</programlisting>
|
|
|
|
<para>
|
|
<literal>$bar</literal> now contains the following key/value
|
|
pairs:
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem><simpara>0 => 0
|
|
<listitem><simpara>1 => 'bob'
|
|
<listitem><simpara>key => 0
|
|
<listitem><simpara>value => 'bob'
|
|
</itemizedlist>
|
|
|
|
<programlisting>
|
|
$foo = array( "Robert" => "Bob", "Seppo" => "Sepi" );
|
|
$bar = each( $foo );
|
|
</programlisting>
|
|
|
|
<para>
|
|
<literal>$bar</literal> now contains the following key/value
|
|
pairs:
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem><simpara>0 => 'Robert'
|
|
<listitem><simpara>1 => 'Bob'
|
|
<listitem><simpara>key => 'Robert'
|
|
<listitem><simpara>value => 'Bob'
|
|
</itemizedlist>
|
|
|
|
</example>
|
|
|
|
<para>
|
|
<function>each</function> is typically used in conjunction with
|
|
<function>list</function> to traverse an array; for instance,
|
|
$HTTP_POST_VARS:
|
|
|
|
<example><title>Traversing $HTTP_POST_VARS with <function>each</function></title>
|
|
<programlisting>
|
|
echo "Values submitted via POST method:<br>";
|
|
while (list($key, $val) = each($HTTP_POST_VARS)) {
|
|
echo "$key => $val<br>";
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
|
|
<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>
|
|
See also <function>key</function>, <function>list</function>,
|
|
<function>current</function>, <function>reset</function>,
|
|
<function>next</function>, and <function>prev</function>.
|
|
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.end">
|
|
<refnamediv>
|
|
<refname>end</refname>
|
|
<refpurpose>Set the internal pointer of an array to its last element</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef><function>end</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>end</function> advances <parameter>array</parameter>'s
|
|
internal pointer to the last element.
|
|
<para>
|
|
See also:
|
|
<function>current</function>, <function>each</function>, <function>end</function>
|
|
<function>next</function> and <function>reset</function>
|
|
</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>
|
|
<funcdef>void <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>
|
|
</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>
|
|
<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
|
|
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 new variable with
|
|
<parameter>prefix</parameter>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>EXTR_PREFIX_ALL</term>
|
|
<listitem>
|
|
<simpara>Prefix all variables with <parameter>prefix</parameter>.</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
If <parameter>extract_type</parameter> is not specified,
|
|
it is assumed to be EXTR_OVERWRITE.
|
|
<para>
|
|
Note that <parameter>prefix</parameter> is only required if
|
|
<parameter>extract_type</parameter> is EXTR_PREFIX_SAME or
|
|
EXTR_PREFIX_ALL.
|
|
<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>
|
|
A possible use for extract is to import into symbol table
|
|
variables contained in an associative array returned by
|
|
<function>wddx_deserialize</function>.
|
|
<para>
|
|
<example>
|
|
<title>extract example</title>
|
|
<programlisting>
|
|
<?
|
|
|
|
/* 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>
|
|
The above example will produce:
|
|
<programlisting>
|
|
blue, large, sphere, medium
|
|
</programlisting>
|
|
|
|
<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.
|
|
</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>
|
|
<funcdef>bool in_array</funcdef>
|
|
<paramdef>mixed <parameter>needle</parameter></paramdef>
|
|
<paramdef>array <parameter>haystack</parameter></paramdef>
|
|
</funcsynopsis>
|
|
|
|
<para>
|
|
Searches <parameter>haystack</parameter> for
|
|
<parameter>needle</parameter> and returns true if it is found in
|
|
the array, false otherwise.
|
|
|
|
<para>
|
|
<example>
|
|
<title><function>in_array</function> example</title>
|
|
<programlisting>
|
|
$os = array("Mac", "NT", "Irix", "Linux");
|
|
if (in_array("Irix", $os))
|
|
print "Got Irix";
|
|
</programlisting>
|
|
</example>
|
|
|
|
<note>
|
|
<para>
|
|
This function was added in PHP 4.0.
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.key">
|
|
<refnamediv>
|
|
<refname>key</refname>
|
|
<refpurpose>Fetch a key from an associative array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>mixed <function>key</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>key</function> returns the index element of the
|
|
current array position.
|
|
<para>
|
|
See also:
|
|
<function>current</function>,
|
|
<function>next</function>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ksort">
|
|
<refnamediv>
|
|
<refname>ksort</refname>
|
|
<refpurpose>Sort an array by key</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>int <function>ksort</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
|
|
<para>
|
|
Sorts an array by key, maintaining key to data correlations. This
|
|
is useful mainly for associative arrays.
|
|
|
|
<example>
|
|
<title><function>ksort</function> example</title>
|
|
<programlisting>
|
|
$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple");
|
|
ksort($fruits);
|
|
for(reset($fruits); $key = key($fruits); next($fruits)) {
|
|
echo "fruits[$key] = ".$fruits[$key]."\n";
|
|
}
|
|
</programlisting></example>
|
|
This example would display:
|
|
<computeroutput>
|
|
fruits[a] = orange
|
|
fruits[b] = banana
|
|
fruits[c] = apple
|
|
fruits[d] = lemon
|
|
</computeroutput>
|
|
|
|
<simpara>
|
|
See also <function>asort</function>, <function>arsort</function>,
|
|
<function>sort</function>, and <function>rsort</function>.
|
|
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.list">
|
|
<refnamediv>
|
|
<refname>list</refname>
|
|
<refpurpose>
|
|
Assign variables as if they were an array
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>void <function>list</function></funcdef>
|
|
<varargs>
|
|
</funcsynopsis>
|
|
<para>
|
|
Like <function>array</function>, this is not really a function,
|
|
but a language construct. <function>list</function> is used to
|
|
assign a list of variables in one operation.
|
|
|
|
<example>
|
|
<title><function>list</function> example</title>
|
|
<programlisting>
|
|
<table>
|
|
<tr>
|
|
<th>Employee name</th>
|
|
<th>Salary</th>
|
|
</tr>
|
|
<?php
|
|
|
|
$result = mysql($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>
|
|
See also: <function>each</function>, <function>array</function>.
|
|
</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>
|
|
<funcdef>mixed <function>next</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns the array element in the next place that's pointed by the
|
|
internal array pointer, or false if there are no more elements.
|
|
<para>
|
|
<function>next</function> behaves like <function>current</function>,
|
|
with one difference. It advances the internal array pointer one
|
|
place forward before returning the element. That means it returns
|
|
the next array element and advances the internal array pointer by
|
|
one. If advancing the internal array pointer results in going beyond
|
|
the end of the element list, <function>next</function> returns false.
|
|
<warning>
|
|
<para>
|
|
If the array contains empty elements 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>
|
|
See also:
|
|
<function>current</function>, <function>end</function>
|
|
<function>prev</function> and <function>reset</function>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.pos">
|
|
<refnamediv>
|
|
<refname>pos</refname>
|
|
<refpurpose>Get the current element from an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>mixed <function>pos</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<simpara>
|
|
This is an alias for <function>current</function>.
|
|
<para>
|
|
See also:
|
|
<function>end</function>, <function>next</function>,
|
|
<function>prev</function> and <function>reset</function>.
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.prev">
|
|
<refnamediv>
|
|
<refname>prev</refname>
|
|
<refpurpose>Rewind the internal array pointer</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>mixed <function>prev</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns the array element in the previous place that's pointed by
|
|
the internal array pointer, or false if there are no more elements.
|
|
|
|
<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>
|
|
<function>prev</function> behaves just like
|
|
<function>next</function>, except it rewinds the internal array
|
|
pointer one place instead of advancing it.
|
|
|
|
<para>
|
|
See also:
|
|
<function>current</function>, <function>end</function>
|
|
<function>next</function> and <function>reset</function>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.range">
|
|
<refnamediv>
|
|
<refname>range</refname>
|
|
<refpurpose>Create an array containing a range of integers</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>array <function>range</function></funcdef>
|
|
<paramdef>int <parameter>low</parameter></paramdef>
|
|
<paramdef>int <parameter>high</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>range</function> returns an array of integers from
|
|
<parameter>low</parameter> to <parameter>high</parameter>,
|
|
inclusive.
|
|
<para>
|
|
See <function>shuffle</function> for an example of its use.
|
|
</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>
|
|
<funcdef>mixed <function>reset</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>reset</function> rewinds <parameter>array</parameter>'s
|
|
internal pointer to the first element.
|
|
<para>
|
|
<function>reset</function> returns the value of the first array
|
|
element.
|
|
<para>
|
|
See also:
|
|
<function>current</function>, <function>each</function>, <function>next</function>
|
|
<function>prev</function> and <function>reset</function>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.rsort">
|
|
<refnamediv>
|
|
<refname>rsort</refname>
|
|
<refpurpose>Sort an array in reverse order</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>void <function>rsort</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function sorts an array in reverse order (highest to lowest).
|
|
<example>
|
|
<title><function>rsort</function> example</title>
|
|
<programlisting>
|
|
$fruits = array("lemon","orange","banana","apple");
|
|
rsort($fruits);
|
|
for (reset($fruits); list($key,$value) = each($fruits); ) {
|
|
echo "fruits[$key] = ", $value, "\n";
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
|
|
This example would display:
|
|
|
|
<computeroutput>
|
|
fruits[0] = orange
|
|
fruits[1] = lemon
|
|
fruits[2] = banana
|
|
fruits[3] = apple
|
|
</computeroutput>
|
|
|
|
The fruits have been sorted in reverse alphabetical order.
|
|
|
|
<para>
|
|
See also <function>arsort</function>, <function>asort</function>,
|
|
<function>ksort</function>, <function>sort</function> and <function>usort</function>.
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.shuffle">
|
|
<refnamediv>
|
|
<refname>shuffle</refname>
|
|
<refpurpose>Shuffle an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>void <function>shuffle</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function shuffles (randomizes the order of the elements in)
|
|
an array.
|
|
<example>
|
|
<title><function>shuffle</function> example</title>
|
|
<programlisting>
|
|
$numbers = range(1,20);
|
|
srand(time());
|
|
shuffle($numbers);
|
|
while (list(,$number) = each($numbers)) {
|
|
echo "$number ";
|
|
}
|
|
</programlisting></example>
|
|
<para>
|
|
See also <function>arsort</function>, <function>asort</function>,
|
|
<function>ksort</function>, <function>rsort</function>,
|
|
<function>sort</function> and <function>usort</function>.
|
|
</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>
|
|
<funcdef>int <function>sizeof</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns the number of elements in the array.
|
|
<para>
|
|
See also:
|
|
<function>count</function>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.sort">
|
|
<refnamediv>
|
|
<refname>sort</refname>
|
|
<refpurpose>Sort an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>void <function>sort</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function sorts an array. Elements will be arranged from lowest to
|
|
highest when this function has completed.
|
|
<example>
|
|
<title><function>sort</function> example</title>
|
|
<programlisting>
|
|
$fruits = array("lemon","orange","banana","apple");
|
|
sort($fruits);
|
|
for(reset($fruits); $key = key($fruits); next($fruits)) {
|
|
echo "fruits[$key] = ".$fruits[$key]."\n";
|
|
}
|
|
</programlisting></example>
|
|
This example would display:
|
|
<computeroutput>
|
|
fruits[0] = apple
|
|
fruits[1] = banana
|
|
fruits[2] = lemon
|
|
fruits[3] = orange
|
|
</computeroutput>
|
|
The fruits have been sorted in alphabetical order.
|
|
<para>
|
|
See also <function>arsort</function>, <function>asort</function>,
|
|
<function>ksort</function>, <function>rsort</function>, and <function>usort</function>.
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.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>
|
|
<funcdef>void <function>uasort</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
<paramdef>function <parameter>cmp_function</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function sorts an array such that array indices maintain their
|
|
correlation with the array elements they are associated with. This is
|
|
used mainly when sorting associative arrays where the actual element
|
|
order is significant. The comparison function is user-defined.
|
|
</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>
|
|
<funcdef>void <function>uksort</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
<paramdef>function <parameter>cmp_function</parameter></paramdef>
|
|
</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.
|
|
|
|
<example>
|
|
<title><function>uksort</function> example</title>
|
|
<programlisting>
|
|
function mycompare($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)) {
|
|
echo "$key: $value\n";
|
|
}
|
|
</programlisting></example>
|
|
|
|
This example would display:
|
|
|
|
<computeroutput>
|
|
20: twenty
|
|
10: ten
|
|
4: four
|
|
3: three
|
|
</computeroutput>
|
|
|
|
<para>
|
|
See also <function>arsort</function>, <function>asort</function>,
|
|
<function>uasort</function>, <function>ksort</function>,
|
|
<function>rsort</function> and <function>sort</function>.
|
|
|
|
</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>
|
|
<funcdef>void <function>usort</function></funcdef>
|
|
<paramdef>array <parameter>array</parameter></paramdef>
|
|
<paramdef>function <parameter>cmp_function</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function will sort an array 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>
|
|
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.
|
|
<example>
|
|
<title><function>usort</function> example</title>
|
|
<programlisting>
|
|
function cmp($a,$b) {
|
|
if ($a == $b) return 0;
|
|
return ($a > $b) ? -1 : 1;
|
|
}
|
|
$a = array(3,2,5,6,1);
|
|
usort($a, cmp);
|
|
while(list($key,$value) = each($a)) {
|
|
echo "$key: $value\n";
|
|
}
|
|
</programlisting></example>
|
|
This example would display:
|
|
<computeroutput>
|
|
0: 6
|
|
1: 5
|
|
2: 3
|
|
3: 2
|
|
4: 1
|
|
</computeroutput>
|
|
|
|
<note>
|
|
<para>
|
|
Obviously in this trivial case the <function>rsort</function> function
|
|
would be more appropriate.
|
|
</para>
|
|
</note>
|
|
|
|
<warning>
|
|
<para>
|
|
The underlying quicksort function in some C libraries (such as on
|
|
Solaris systems) may cause PHP to crash if the comparison function
|
|
does not return consistent values.
|
|
</para>
|
|
</warning>
|
|
|
|
<para>
|
|
See also:
|
|
<function>arsort</function>, <function>asort</function>,
|
|
<function>ksort</function>, <function>rsort</function> and
|
|
<function>sort</function>.
|
|
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
</reference>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|