mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 17:08:54 +00:00
26b40435b4
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@100472 c90b9560-bf6c-de11-be94-00142212c4b1
4015 lines
114 KiB
XML
4015 lines
114 KiB
XML
<!-- D O N O T E D I T T H I S F I L E ! ! !
|
|
|
|
it is still here for historical reasons only
|
|
(as translators may need to check old revision diffs)
|
|
|
|
if you want to change things documented in this file
|
|
you should now edit the files found under en/reference
|
|
instead -->
|
|
|
|
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.175 $ -->
|
|
<reference id="ref.array">
|
|
<title>Array Functions</title>
|
|
<titleabbrev>Arrays</titleabbrev>
|
|
|
|
<partintro>
|
|
<para id="array.intro">
|
|
These functions allow you to interact with and manipulate
|
|
arrays in various ways. Arrays are essential for storing,
|
|
managing, and operating on sets of variables.
|
|
</para>
|
|
<para>
|
|
Simple and multi-dimensional arrays are supported, and may be
|
|
either user created or created by another function.
|
|
There are specific database handling functions for populating
|
|
arrays from database queries, and several functions return arrays.
|
|
</para>
|
|
<para>
|
|
Please see the <link linkend="language.types.array">Arrays</link>
|
|
section of the manual for a detailed explanation of how arrays are
|
|
implemented and used in PHP.
|
|
</para>
|
|
|
|
<section id="array.requirements">
|
|
<title>Requirements</title>
|
|
<para>
|
|
These functions are available as part of the standard module, which is
|
|
always available.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="array.installation">
|
|
<title>Installation</title>
|
|
<para>
|
|
There is no installation needed to use these functions, they are part of
|
|
the PHP core.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="array.configuration">
|
|
<title>Runtime Configuration</title>
|
|
&no.config;
|
|
</section>
|
|
|
|
<section id="array.resources">
|
|
<title>Resource types</title>
|
|
&no.resource;
|
|
</section>
|
|
|
|
<section id="array.constants">
|
|
<title>Predefined constants</title>
|
|
<para>
|
|
<constant>CASE_UPPER</constant> and <constant>CASE_LOWER</constant> are
|
|
used with the <function>array_change_key_case</function> function. They
|
|
respectively are used for changing a string to upper case or lower case.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="array.seealso">
|
|
<title>See also</title>
|
|
<para>
|
|
See also <function>is_array</function>, <function>explode</function>,
|
|
<function>implode</function>, <function>split</function>,
|
|
and <function>join</function>.
|
|
</para>
|
|
</section>
|
|
</partintro>
|
|
|
|
<refentry id="function.array">
|
|
<refnamediv>
|
|
<refname>array</refname>
|
|
<refpurpose>
|
|
Create an array
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array</methodname>
|
|
<methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Returns an array of the parameters. The parameters can be given
|
|
an index with the <literal>=></literal> operator.
|
|
</para>
|
|
<para>
|
|
<note>
|
|
<para>
|
|
<function>array</function> is a language construct used to
|
|
represent literal arrays, and not a regular function.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
<para>
|
|
Syntax "index => values", separated by commas, define index
|
|
and values. index may be of type string or numeric. When index is
|
|
omitted, a integer index is automatically generated, starting
|
|
at 0. If index is an integer, next generated index will
|
|
be the biggest integer index + 1. Note that when two identical
|
|
index are defined, the last overwrite the first.
|
|
</para>
|
|
<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 role="php">
|
|
<![CDATA[
|
|
$fruits = array (
|
|
"fruits" => array ("a"=>"orange", "b"=>"banana", "c"=>"apple"),
|
|
"numbers" => array (1, 2, 3, 4, 5, 6),
|
|
"holes" => array ("first", 5 => "second", "third")
|
|
);
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Automatic index with <function>array</function></title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$array = array( 1, 1, 1, 1, 1, 8=>1, 4=>1, 19, 3=>13);
|
|
print_r($array);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
will display :
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[0] => 1
|
|
[1] => 1
|
|
[2] => 1
|
|
[3] => 13
|
|
[4] => 1
|
|
[8] => 1
|
|
[9] => 19
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
Note that index '3' is defined twice, and keep its final value of 13.
|
|
Index 4 is defined after index 8, and next generated index (value 19)
|
|
is 9, since biggest index was 8.
|
|
</para>
|
|
<para>
|
|
This example creates a 1-based array.
|
|
<example>
|
|
<title>1-based index with <function>array</function></title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$firstquarter = array(1 => 'January', 'February', 'March');
|
|
print_r($firstquarter);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
will display :
|
|
<screen>
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[1] => 'January'
|
|
[2] => 'February'
|
|
[3] => 'March'
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>array_pad</function>,
|
|
<function>list</function>, and <function>range</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-change-key-case">
|
|
<refnamediv>
|
|
<refname>array_change_key_case</refname>
|
|
<refpurpose>Returns an array with all string keys lowercased or uppercased</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_change_key_case</methodname>
|
|
<methodparam><type>array</type><parameter>input</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>case</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_change_key_case</function> changes the
|
|
keys in the <parameter>input</parameter> array to
|
|
be all lowercase or uppercase. The change depends
|
|
on the last optional <parameter>case</parameter>
|
|
parameter. You can pass two constants there,
|
|
<constant>CASE_UPPER</constant> and
|
|
<constant>CASE_LOWER</constant>. The default is
|
|
<constant>CASE_LOWER</constant>. The function will leave
|
|
number indices as is.
|
|
</para>
|
|
<example>
|
|
<title><function>array_change_key_case</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$input_array = array("FirSt" => 1, "SecOnd" => 4);
|
|
print_r(array_change_key_case($input_array, CASE_UPPER));
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The printout of the above program will be:
|
|
<screen>
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[FIRST] => 1
|
|
[SECOND] => 2
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-chunk">
|
|
<refnamediv>
|
|
<refname>array_chunk</refname>
|
|
<refpurpose>Split an array into chunks</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_chunk</methodname>
|
|
<methodparam><type>array</type><parameter>input</parameter></methodparam>
|
|
<methodparam><type>int</type><parameter>size</parameter></methodparam>
|
|
<methodparam choice="opt"><type>bool</type><parameter>preserve_keys</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_chunk</function> splits the array into
|
|
several arrays with <parameter>size</parameter> values
|
|
in them. You may also have an array with less values
|
|
at the end. You get the arrays as members of a
|
|
multidimensional array indexed with numbers starting
|
|
from zero.
|
|
</para>
|
|
<para>
|
|
By setting the optional <parameter>preserve_keys</parameter>
|
|
parameter to &true;, you can force PHP to preserve the original
|
|
keys from the input array. If you specify &false; new number
|
|
indices will be used in each resulting array with
|
|
indices starting from zero. The default is &false;.
|
|
</para>
|
|
<example>
|
|
<title><function>array_chunk</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$input_array = array('a', 'b', 'c', 'd', 'e');
|
|
print_r(array_chunk($input_array, 2));
|
|
print_r(array_chunk($input_array, 2, TRUE));
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The printout of the above program will be:
|
|
<screen>
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[0] => Array
|
|
(
|
|
[0] => a
|
|
[1] => b
|
|
)
|
|
|
|
[1] => Array
|
|
(
|
|
[0] => c
|
|
[1] => d
|
|
)
|
|
|
|
[2] => Array
|
|
(
|
|
[0] => e
|
|
)
|
|
|
|
)
|
|
Array
|
|
(
|
|
[0] => Array
|
|
(
|
|
[0] => a
|
|
[1] => b
|
|
)
|
|
|
|
[1] => Array
|
|
(
|
|
[2] => c
|
|
[3] => d
|
|
)
|
|
|
|
[2] => Array
|
|
(
|
|
[4] => e
|
|
)
|
|
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-count-values">
|
|
<refnamediv>
|
|
<refname>array_count_values</refname>
|
|
<refpurpose>Counts all the values of an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_count_values</methodname>
|
|
<methodparam><type>array</type><parameter>input</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_count_values</function> returns an array using
|
|
the values of the <parameter>input</parameter> array as keys and
|
|
their frequency in <parameter>input</parameter> as values.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_count_values</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$array = array (1, "hello", 1, "world", "hello");
|
|
print_r(array_count_values ($array));
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The printout of the above program will be:
|
|
<screen>
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[1] => 2
|
|
[hello] => 2
|
|
[world] => 1
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-diff">
|
|
<refnamediv>
|
|
<refname>array_diff</refname>
|
|
<refpurpose>Computes the difference of arrays</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_diff</methodname>
|
|
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
|
|
<methodparam><type>array</type><parameter>array2</parameter></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter> ...</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_diff</function> returns an array
|
|
containing all the values of <parameter>array1</parameter>
|
|
that are not present in any of the other arguments.
|
|
Note that keys are preserved.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_diff</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$array1 = array ("a" => "green", "red", "blue", "red");
|
|
$array2 = array ("b" => "green", "yellow", "red");
|
|
$result = array_diff ($array1, $array2);
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
This makes <varname>$result</varname> have
|
|
<literal>array ("blue");</literal>. Multiple occurrences in
|
|
$array1 are all treated the same way.
|
|
</para>
|
|
<note>
|
|
<simpara>
|
|
Two elements are considered equal if and only if
|
|
<literal>(string) $elem1 === (string) $elem2</literal>. In words:
|
|
when the string representation is the same.
|
|
<!-- TODO: example of it... -->
|
|
</simpara>
|
|
</note>
|
|
<warning>
|
|
<simpara>
|
|
This was broken in PHP 4.0.4!
|
|
<!-- TODO: when exactly was this broken?... -->
|
|
</simpara>
|
|
</warning>
|
|
<para>
|
|
See also <function>array_intersect</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-filter">
|
|
<refnamediv>
|
|
<refname>array_filter</refname>
|
|
<refpurpose>
|
|
Filters elements of an array using a callback function
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_filter</methodname>
|
|
<methodparam><type>array</type><parameter>input</parameter></methodparam>
|
|
<methodparam choice="opt"><type>mixed</type><parameter>callback</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_filter</function> returns an array
|
|
containing all the elements of <parameter>input</parameter>
|
|
filtered according a callback function. If the
|
|
<parameter>input</parameter> is an associative array
|
|
the keys are preserved.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_filter</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function odd($var) {
|
|
return ($var % 2 == 1);
|
|
}
|
|
|
|
function even($var) {
|
|
return ($var % 2 == 0);
|
|
}
|
|
|
|
$array1 = array ("a"=>1, "b"=>2, "c"=>3, "d"=>4, "e"=>5);
|
|
$array2 = array (6, 7, 8, 9, 10, 11, 12);
|
|
|
|
echo "Odd :\n";
|
|
print_r(array_filter($array1, "odd"));
|
|
echo "Even:\n";
|
|
print_r(array_filter($array2, "even"));
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The printout of the program above will be:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Odd :
|
|
Array
|
|
(
|
|
[a] => 1
|
|
[c] => 3
|
|
[e] => 5
|
|
)
|
|
Even:
|
|
Array
|
|
(
|
|
[0] => 6
|
|
[2] => 8
|
|
[4] => 10
|
|
[6] => 12
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
¬e.func-callback;
|
|
<para>
|
|
Users may not change the array itself from the callback
|
|
function. e.g. Add/delete an element, unset the array that
|
|
<function>array_filter</function> is applied to. If the array
|
|
is changed, the behavior of this function is undefined.
|
|
</para>
|
|
<para>
|
|
See also <function>array_map</function> and
|
|
<function>array_reduce</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-flip">
|
|
<refnamediv>
|
|
<refname>array_flip</refname>
|
|
<refpurpose>Flip all the values of an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_flip</methodname>
|
|
<methodparam><type>array</type><parameter>trans</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_flip</function> returns an <type>array</type> in flip
|
|
order, i.e. keys from <parameter>trans</parameter> become values and
|
|
<parameter>trans</parameter>'s values become keys.
|
|
</para>
|
|
<para>
|
|
Note that the values of <parameter>trans</parameter> need to be valid
|
|
keys, i.e. they need to be either <type>integer</type> or
|
|
<type>string</type>. A warning will be emitted if a value has the wrong
|
|
type, and the key/value pair in question <emphasis>will not be
|
|
flipped</emphasis>.
|
|
</para>
|
|
<para>
|
|
If a value has several occurrences, the latest key will be
|
|
used as its values, and all others will be lost.
|
|
</para>
|
|
<para>
|
|
<function>array_flip</function> returns &false;
|
|
if it fails.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_flip</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$trans = array_flip ($trans);
|
|
$original = strtr ($str, $trans);
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_flip</function> example : collision</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$trans = array ("a" => 1, "b" => 1, "c" => 2);
|
|
$trans = array_flip ($trans);
|
|
print_r($trans);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
now $trans is :
|
|
<screen>
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[1] => b
|
|
[2] => c
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-fill">
|
|
<refnamediv>
|
|
<refname>array_fill</refname>
|
|
<refpurpose>Fill an array with values</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_fill</methodname>
|
|
<methodparam><type>int</type><parameter>start_index</parameter></methodparam>
|
|
<methodparam><type>int</type><parameter>num</parameter></methodparam>
|
|
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_fill</function> fills an array with
|
|
<parameter>num</parameter> entries of the value of the
|
|
<parameter>value</parameter> parameter, keys starting at the
|
|
<parameter>start_index</parameter> parameter.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_fill</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$a = array_fill(5, 6, 'banana');
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
$a now has the following entries using <function>print_r</function>:
|
|
<screen>
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[5] => banana
|
|
[6] => banana
|
|
[7] => banana
|
|
[8] => banana
|
|
[9] => banana
|
|
[10] => banana
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-intersect">
|
|
<refnamediv>
|
|
<refname>array_intersect</refname>
|
|
<refpurpose>Computes the intersection of arrays</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_intersect</methodname>
|
|
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
|
|
<methodparam><type>array</type><parameter>array2</parameter></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter> ...</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_intersect</function> returns an array
|
|
containing all the values of <parameter>array1</parameter>
|
|
that are present in all the arguments.
|
|
Note that keys are preserved.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_intersect</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$array1 = array ("a" => "green", "red", "blue");
|
|
$array2 = array ("b" => "green", "yellow", "red");
|
|
$result = array_intersect ($array1, $array2);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This makes <varname>$result</varname> have
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[a] => green
|
|
[0] => red
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<note>
|
|
<simpara>
|
|
Two elements are considered equal if and only if
|
|
<literal>(string) $elem1 === (string) $elem2</literal>. In words:
|
|
when the string representation is the same.
|
|
<!-- TODO: example of it... -->
|
|
</simpara>
|
|
</note>
|
|
<warning>
|
|
<simpara>
|
|
This was broken in PHP 4.0.4!
|
|
<!-- TODO: when exactly was this broken?... -->
|
|
</simpara>
|
|
</warning>
|
|
<para>
|
|
See also <function>array_diff</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-key-exists">
|
|
<refnamediv>
|
|
<refname>array_key_exists</refname>
|
|
<refpurpose>Checks if the given key or index exists in the array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>bool</type><methodname>array_key_exists</methodname>
|
|
<methodparam><type>mixed</type><parameter>key</parameter></methodparam>
|
|
<methodparam><type>array</type><parameter>search</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_key_exists</function> returns &true; if the
|
|
given <parameter>key</parameter> is set in the array.
|
|
<parameter>key</parameter> can be any value possible
|
|
for an array index.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_key_exists</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$search_array = array("first" => 1, "second" => 4);
|
|
if (array_key_exists("first", $search_array)) {
|
|
echo "The 'first' element is in the array";
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<note>
|
|
<simpara>
|
|
This name of this function is <function>key_exists</function>
|
|
in PHP version 4.0.6.
|
|
</simpara>
|
|
</note>
|
|
<para>
|
|
See also <function>isset</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-keys">
|
|
<refnamediv>
|
|
<refname>array_keys</refname>
|
|
<refpurpose>Return all the keys of an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_keys</methodname>
|
|
<methodparam><type>array</type><parameter>input</parameter></methodparam>
|
|
<methodparam choice="opt"><type>mixed</type><parameter>
|
|
search_value
|
|
</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_keys</function> returns the keys, numeric and
|
|
string, from the <parameter>input</parameter> array.
|
|
</para>
|
|
<para>
|
|
If the optional <parameter>search_value</parameter> is specified,
|
|
then only the keys for that value are returned. Otherwise, all
|
|
the keys from the <parameter>input</parameter> are returned.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_keys</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$array = array (0 => 100, "color" => "red");
|
|
print_r(array_keys ($array));
|
|
|
|
$array = array ("blue", "red", "green", "blue", "blue");
|
|
print_r(array_keys ($array, "blue"));
|
|
|
|
$array = array ("color" => array("blue", "red", "green"), "size" => array("small", "medium", "large"));
|
|
print_r(array_keys ($array));
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The printout of the program above will be:
|
|
<screen>
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[0] => 0
|
|
[1] => color
|
|
)
|
|
Array
|
|
(
|
|
[0] => 0
|
|
[1] => 3
|
|
[2] => 4
|
|
)
|
|
Array
|
|
(
|
|
[0] => color
|
|
[1] => size
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
This function was added to PHP 4, below is an implementation for
|
|
those still using PHP 3.
|
|
<example>
|
|
<title>
|
|
Implementation of <function>array_keys</function> for PHP 3
|
|
users
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function array_keys ($arr, $term="") {
|
|
$t = array();
|
|
while (list($k,$v) = each($arr)) {
|
|
if ($term && $v != $term) {
|
|
continue;
|
|
}
|
|
$t[] = $k;
|
|
}
|
|
return $t;
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</note>
|
|
<para>
|
|
See also <function>array_values</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-map">
|
|
<refnamediv>
|
|
<refname>array_map</refname>
|
|
<refpurpose>
|
|
Applies the callback to the elements of the given arrays
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_map</methodname>
|
|
<methodparam><type>mixed</type><parameter>callback</parameter></methodparam>
|
|
<methodparam><type>array</type><parameter>arr1</parameter></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter>arr2...</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_map</function> returns an array containing all
|
|
the elements of <parameter>arr1</parameter> after applying the
|
|
callback function to each one. The number of parameters that the
|
|
callback function accepts should match the number of arrays
|
|
passed to the <function>array_map</function>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_map</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function cube($n) {
|
|
return $n*$n*$n;
|
|
}
|
|
|
|
$a = array(1, 2, 3, 4, 5);
|
|
$b = array_map("cube", $a);
|
|
print_r($b);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This makes <varname>$b</varname> have:
|
|
<screen>
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[0] => 1
|
|
[1] => 8
|
|
[2] => 27
|
|
[3] => 64
|
|
[4] => 125
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_map</function> - using more arrays</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function show_Spanish($n, $m) {
|
|
return "The number $n is called $m in Spanish";
|
|
}
|
|
|
|
function map_Spanish($n, $m) {
|
|
return array ($n => $m);
|
|
}
|
|
|
|
$a = array(1, 2, 3, 4, 5);
|
|
$b = array("uno", "dos", "tres", "cuatro", "cinco");
|
|
|
|
$c = array_map("show_Spanish", $a, $b);
|
|
print_r($c);
|
|
|
|
$d = array_map("map_Spanish", $a , $b);
|
|
print_r($d);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This results:
|
|
<screen>
|
|
<![CDATA[
|
|
// printout of $c
|
|
Array
|
|
(
|
|
[0] => The number 1 is called uno in Spanish
|
|
[1] => The number 2 is called dos in Spanish
|
|
[2] => The number 3 is called tres in Spanish
|
|
[3] => The number 4 is called cuatro in Spanish
|
|
[4] => The number 5 is called cinco in Spanish
|
|
)
|
|
|
|
// printout of $d
|
|
Array
|
|
(
|
|
[0] => Array
|
|
(
|
|
[1] => uno
|
|
)
|
|
|
|
[1] => Array
|
|
(
|
|
[2] => dos
|
|
)
|
|
|
|
[2] => Array
|
|
(
|
|
[3] => tres
|
|
)
|
|
|
|
[3] => Array
|
|
(
|
|
[4] => cuatro
|
|
)
|
|
|
|
[4] => Array
|
|
(
|
|
[5] => cinco
|
|
)
|
|
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
Usually when using two or more arrays, they should be of equal length
|
|
because the callback function is applied in parallel to the corresponding
|
|
elements.
|
|
If the arrays are of unequal length, the shortest one will be extended
|
|
with empty elements.
|
|
</para>
|
|
<para>
|
|
An interesting use of this function is to construct an array of arrays,
|
|
which can be easily performed by using &null;
|
|
as the name of the callback function
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Creating an array of arrays</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$a = array(1, 2, 3, 4, 5);
|
|
$b = array("one", "two", "three", "four", "five");
|
|
$c = array("uno", "dos", "tres", "cuatro", "cinco");
|
|
|
|
$d = array_map(null, $a, $b, $c);
|
|
print_r($d);
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
The printout of the program above will be:
|
|
<screen>
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[0] => Array
|
|
(
|
|
[0] => 1
|
|
[1] => one
|
|
[2] => uno
|
|
)
|
|
|
|
[1] => Array
|
|
(
|
|
[0] => 2
|
|
[1] => two
|
|
[2] => dos
|
|
)
|
|
|
|
[2] => Array
|
|
(
|
|
[0] => 3
|
|
[1] => three
|
|
[2] => tres
|
|
)
|
|
|
|
[3] => Array
|
|
(
|
|
[0] => 4
|
|
[1] => four
|
|
[2] => cuatro
|
|
)
|
|
|
|
[4] => Array
|
|
(
|
|
[0] => 5
|
|
[1] => five
|
|
[2] => cinco
|
|
)
|
|
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
See also <function>array_filter</function> and
|
|
<function>array_reduce</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-merge">
|
|
<refnamediv>
|
|
<refname>array_merge</refname>
|
|
<refpurpose>Merge two or more arrays</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_merge</methodname>
|
|
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
|
|
<methodparam><type>array</type><parameter>array2</parameter></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_merge</function> merges the elements of two or
|
|
more arrays together so that the values of one are appended to
|
|
the end of the previous one. It returns the resulting array.
|
|
</para>
|
|
<para>
|
|
If the input arrays have the same string keys, then the later
|
|
value for that key will overwrite the previous one. If, however,
|
|
the arrays have the same numeric key, the later value will not
|
|
overwrite the original value, but will be appended.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_merge</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$array1 = array ("color" => "red", 2, 4);
|
|
$array2 = array ("a", "b", "color" => "green", "shape" => "trapezoid", 4);
|
|
$result = array_merge ($array1, $array2);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The <literal>$result</literal> will be:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[color] => green
|
|
[0] => 2
|
|
[1] => 4
|
|
[2] => a
|
|
[3] => b
|
|
[shape] => trapezoid
|
|
[4] => 4
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>array_merge_recursive</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-merge-recursive">
|
|
<refnamediv>
|
|
<refname>array_merge_recursive</refname>
|
|
<refpurpose>Merge two or more arrays recursively</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_merge_recursive</methodname>
|
|
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
|
|
<methodparam><type>array</type><parameter>array2</parameter></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_merge_recursive</function> merges the elements of
|
|
two or more arrays together so that the values of one are appended
|
|
to the end of the previous one. It returns the resulting array.
|
|
</para>
|
|
<para>
|
|
If the input arrays have the same string keys, then the values for
|
|
these keys are merged together into an array, and this is done
|
|
recursively, so that if one of the values is an array itself, the
|
|
function will merge it with a corresponding entry in another array
|
|
too. If, however, the arrays have the same numeric key, the later
|
|
value will not overwrite the original value, but will be appended.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_merge_recursive</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$ar1 = array ("color" => array ("favorite" => "red"), 5);
|
|
$ar2 = array (10, "color" => array ("favorite" => "green", "blue"));
|
|
$result = array_merge_recursive ($ar1, $ar2);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The <literal>$result</literal> will be:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[color] => Array
|
|
(
|
|
[favorite] => Array
|
|
(
|
|
[0] => red
|
|
[1] => green
|
|
)
|
|
|
|
[0] => blue
|
|
)
|
|
|
|
[0] => 5
|
|
[1] => 10
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>array_merge</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-multisort">
|
|
<refnamediv>
|
|
<refname>array_multisort</refname>
|
|
<refpurpose>Sort multiple or multi-dimensional arrays</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>bool</type><methodname>array_multisort</methodname>
|
|
<methodparam><type>array</type><parameter>ar1</parameter></methodparam>
|
|
<methodparam choice="opt"><type>mixed</type><parameter>arg</parameter></methodparam>
|
|
<methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_multisort</function> can be used to sort several
|
|
arrays at once or a multi-dimensional array according by one of
|
|
more dimensions. It maintains key association when sorting.
|
|
</para>
|
|
<para>
|
|
The input arrays are treated as columns of a table to be sorted
|
|
by rows - this resembles the functionality of SQL ORDER BY
|
|
clause. The first array is the primary one to sort by. The rows
|
|
(values) in that array that compare the same are sorted by the
|
|
next input array, and so on.
|
|
</para>
|
|
<para>
|
|
The argument structure of this function is a bit unusual, but
|
|
flexible. The very first argument has to be an
|
|
array. Subsequently, each argument can be either an array or a
|
|
sorting flag from the following lists.
|
|
</para>
|
|
<para>
|
|
Sorting order flags:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>SORT_ASC - sort in ascending order</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>SORT_DESC - sort in descending order</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Sorting type flags:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>SORT_REGULAR - compare items normally</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>SORT_NUMERIC - compare items numerically</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>SORT_STRING - compare items as strings</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
No two sorting flags of the same type can be specified after each
|
|
array. The sorting flags specified after an array argument apply
|
|
only to that array - they are reset to default SORT_ASC and
|
|
SORT_REGULAR after before each new array argument.
|
|
</para>
|
|
<para>
|
|
&return.success;
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Sorting multiple arrays</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$ar1 = array ("10", 100, 100, "a");
|
|
$ar2 = array (1, 3, "2", 1);
|
|
array_multisort ($ar1, $ar2);
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
In this example, after sorting, the first array will contain 10,
|
|
"a", 100, 100. The second array will contain 1, 1, "2", 3. The
|
|
entries in the second array corresponding to the identical
|
|
entries in the first array (100 and 100) were sorted as well.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Sorting multi-dimensional array</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$ar = array (array ("10", 100, 100, "a"), array (1, 3, "2", 1));
|
|
array_multisort ($ar[0], SORT_ASC, SORT_STRING,
|
|
$ar[1], SORT_NUMERIC, SORT_DESC);
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
In this example, after sorting, the first array will contain 10,
|
|
100, 100, "a" (it was sorted as strings in ascending order), and
|
|
the second one will contain 1, 3, "2", 1 (sorted as numbers, in
|
|
descending order).
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-pad">
|
|
<refnamediv>
|
|
<refname>array_pad</refname>
|
|
<refpurpose>
|
|
Pad array to the specified length with a value
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_pad</methodname>
|
|
<methodparam><type>array</type><parameter>input</parameter></methodparam>
|
|
<methodparam><type>int</type><parameter>pad_size</parameter></methodparam>
|
|
<methodparam><type>mixed</type><parameter>pad_value</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_pad</function> returns a copy of the
|
|
<parameter>input</parameter> padded to size specified by
|
|
<parameter>pad_size</parameter> with value
|
|
<parameter>pad_value</parameter>. If
|
|
<parameter>pad_size</parameter> is positive then the array is
|
|
padded on the right, if it's negative then on the left. If the
|
|
absolute value of <parameter>pad_size</parameter> is less than or
|
|
equal to the length of the <parameter>input</parameter> then no
|
|
padding takes place.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_pad</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$input = array (12, 10, 9);
|
|
|
|
$result = array_pad ($input, 5, 0);
|
|
// result is array (12, 10, 9, 0, 0)
|
|
|
|
$result = array_pad ($input, -7, -1);
|
|
// result is array (-1, -1, -1, -1, 12, 10, 9)
|
|
|
|
$result = array_pad ($input, 2, "noop");
|
|
// not padded
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-pop">
|
|
<refnamediv>
|
|
<refname>array_pop</refname>
|
|
<refpurpose>Pop the element off the end of array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>array_pop</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_pop</function> pops and returns the last value of
|
|
the <parameter>array</parameter>, shortening the
|
|
<parameter>array</parameter> by one element.
|
|
If <parameter>array</parameter> is empty (or is not an array),
|
|
&null; will be returned.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_pop</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$stack = array ("orange", "banana", "apple", "raspberry");
|
|
$fruit = array_pop ($stack);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
After this, <varname>$stack</varname> will have only 3 elements:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[0] => orange
|
|
[1] => banana
|
|
[2] => apple
|
|
)
|
|
]]>
|
|
</screen>
|
|
and <literal>rasberry</literal> will be assigned to
|
|
<varname>$fruit</varname>.
|
|
</para>
|
|
</example>
|
|
</para>
|
|
&return.falseproblem;
|
|
<para>
|
|
See also <function>array_push</function>,
|
|
<function>array_shift</function>, and
|
|
<function>array_unshift</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-push">
|
|
<refnamediv>
|
|
<refname>array_push</refname>
|
|
<refpurpose>
|
|
Push one or more elements onto the end of array
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>array_push</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
<methodparam><type>mixed</type><parameter>var</parameter></methodparam>
|
|
<methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_push</function> treats
|
|
<parameter>array</parameter> as a stack, and pushes the passed
|
|
variables onto the end of <parameter>array</parameter>. The
|
|
length of <parameter>array</parameter> increases by the number of
|
|
variables pushed. Has the same effect as:
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$array[] = $var;
|
|
]]>
|
|
</programlisting>
|
|
repeated for each <parameter>var</parameter>.
|
|
</para>
|
|
<para>
|
|
Returns the new number of elements in the array.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_push</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$stack = array ("orange", "banana");
|
|
array_push ($stack, "apple", "raspberry");
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This example would result in <varname>$stack</varname> having
|
|
the following elements:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[0] => orange
|
|
[1] => banana
|
|
[2] => apple
|
|
[3] => raspberry
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>array_pop</function>,
|
|
<function>array_shift</function>, and
|
|
<function>array_unshift</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-rand">
|
|
<refnamediv>
|
|
<refname>array_rand</refname>
|
|
<refpurpose>
|
|
Pick one or more random entries out of an array
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>array_rand</methodname>
|
|
<methodparam><type>array</type><parameter>input</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>num_req</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_rand</function> is rather useful when you want to
|
|
pick one or more random entries out of an array. It takes an
|
|
<parameter>input</parameter> array and an optional argument
|
|
<parameter>num_req</parameter> which specifies how many entries you
|
|
want to pick - if not specified, it defaults to 1.
|
|
</para>
|
|
<para>
|
|
If you are picking only one entry, <function>array_rand</function>
|
|
returns the key for a random entry. Otherwise, it returns an array
|
|
of keys for the random entries. This is done so that you can pick
|
|
random keys as well as values out of the array.
|
|
</para>
|
|
<para>
|
|
Don't forget to call <function>srand</function> to seed the random
|
|
number generator.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_rand</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
srand ((float) microtime() * 10000000);
|
|
$input = array ("Neo", "Morpheus", "Trinity", "Cypher", "Tank");
|
|
$rand_keys = array_rand ($input, 2);
|
|
print $input[$rand_keys[0]]."\n";
|
|
print $input[$rand_keys[1]]."\n";
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-reverse">
|
|
<refnamediv>
|
|
<refname>array_reverse</refname>
|
|
<refpurpose>
|
|
Return an array with elements in reverse order
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_reverse</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
<methodparam choice="opt"><type>bool</type><parameter>preserve_keys</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_reverse</function> takes input
|
|
<parameter>array</parameter> and returns a new array with the
|
|
order of the elements reversed, preserving the keys if
|
|
<parameter>preserve_keys</parameter> is &true;.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_reverse</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$input = array ("php", 4.0, array ("green", "red"));
|
|
$result = array_reverse ($input);
|
|
$result_keyed = array_reverse ($input, TRUE);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This makes both <varname>$result</varname> and
|
|
<varname>$result_keyed</varname> have the same elements, but
|
|
note the difference between the keys. The printout of
|
|
<varname>$result</varname> and
|
|
<varname>$result_keyed</varname> will be:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[0] => Array
|
|
(
|
|
[0] => green
|
|
[1] => red
|
|
)
|
|
|
|
[1] => 4
|
|
[2] => php
|
|
)
|
|
Array
|
|
(
|
|
[2] => Array
|
|
(
|
|
[0] => green
|
|
[1] => red
|
|
)
|
|
|
|
[1] => 4
|
|
[0] => php
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
|
|
</example>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
The second parameter was added in PHP 4.0.3.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-reduce">
|
|
<refnamediv>
|
|
<refname>array_reduce</refname>
|
|
<refpurpose>
|
|
Iteratively reduce the array to a single value using a callback
|
|
function
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>array_reduce</methodname>
|
|
<methodparam><type>array</type><parameter>input</parameter></methodparam>
|
|
<methodparam><type>mixed</type><parameter>callback</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>initial</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_reduce</function> applies iteratively the
|
|
<parameter>callback</parameter> function to the elements of the
|
|
array <parameter>input</parameter>, so as to reduce the array to
|
|
a single value. If the optional <parameter>initial</parameter> is
|
|
available, it will be used at the beginning of the process, or as
|
|
a final result in case the array is empty.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_reduce</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function rsum($v, $w) {
|
|
$v += $w;
|
|
return $v;
|
|
}
|
|
|
|
function rmul($v, $w) {
|
|
$v *= $w;
|
|
return $v;
|
|
}
|
|
|
|
$a = array(1, 2, 3, 4, 5);
|
|
$x = array();
|
|
$b = array_reduce($a, "rsum");
|
|
$c = array_reduce($a, "rmul", 10);
|
|
$d = array_reduce($x, "rsum", 1);
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
This will result in <varname>$b</varname> containing
|
|
<literal>15</literal>, <varname>$c</varname> containing
|
|
<literal>1200</literal> (= 1*2*3*4*5*10), and
|
|
<varname>$d</varname> containing <literal>1</literal>.
|
|
</para>
|
|
<para>
|
|
See also <function>array_filter</function> and
|
|
<function>array_map</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-shift">
|
|
<refnamediv>
|
|
<refname>array_shift</refname>
|
|
<refpurpose>
|
|
Shift an element off the beginning of array
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>array_shift</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_shift</function> shifts the first value of the
|
|
<parameter>array</parameter> off and returns it, shortening the
|
|
<parameter>array</parameter> by one element and moving everything
|
|
down. If <parameter>array</parameter> is empty (or is not an
|
|
array), &null; will be returned.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_shift</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$stack = array ("orange", "banana", "apple", "raspberry");
|
|
$fruit = array_shift ($stack);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This would result in <varname>$stack</varname> having 3 elements left:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[0] => banana
|
|
[1] => apple
|
|
[2] => raspberry
|
|
)
|
|
]]>
|
|
</screen>
|
|
and <literal>orange</literal> will be assigned to
|
|
<varname>$fruit</varname>.
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>array_unshift</function>,
|
|
<function>array_push</function>, and
|
|
<function>array_pop</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-slice">
|
|
<refnamediv>
|
|
<refname>array_slice</refname>
|
|
<refpurpose>Extract a slice of the array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_slice</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
<methodparam><type>int</type><parameter>offset</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>
|
|
length
|
|
</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_slice</function> returns the sequence of elements
|
|
from the array <parameter>array</parameter> as specified by the
|
|
<parameter>offset</parameter> and <parameter>length</parameter>
|
|
parameters.
|
|
</para>
|
|
<para>
|
|
If <parameter>offset</parameter> is positive, the sequence will
|
|
start at that offset in the <parameter>array</parameter>. If
|
|
<parameter>offset</parameter> is negative, the sequence will
|
|
start that far from the end of the <parameter>array</parameter>.
|
|
</para>
|
|
<para>
|
|
If <parameter>length</parameter> is given and is positive, then
|
|
the sequence will have that many elements in it. If
|
|
<parameter>length</parameter> is given and is negative then the
|
|
sequence will stop that many elements from the end of the
|
|
array. If it is omitted, then the sequence will have everything
|
|
from <parameter>offset</parameter> up until the end of the
|
|
<parameter>array</parameter>.
|
|
</para>
|
|
<para>
|
|
Note that <function>array_slice</function> will ignore array
|
|
keys, and will calculate offsets and lengths based on the
|
|
actual positions of elements within the array.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_slice</function> examples</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$input = array ("a", "b", "c", "d", "e");
|
|
|
|
$output = array_slice ($input, 2); // returns "c", "d", and "e"
|
|
$output = array_slice ($input, 2, -1); // returns "c", "d"
|
|
$output = array_slice ($input, -2, 1); // returns "d"
|
|
$output = array_slice ($input, 0, 3); // returns "a", "b", and "c"
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>array_splice</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-splice">
|
|
<refnamediv>
|
|
<refname>array_splice</refname>
|
|
<refpurpose>
|
|
Remove a portion of the array and replace it with something
|
|
else
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_splice</methodname>
|
|
<methodparam><type>array</type><parameter>input</parameter></methodparam>
|
|
<methodparam><type>int</type><parameter>offset</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter>
|
|
replacement
|
|
</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_splice</function> removes the elements designated
|
|
by <parameter>offset</parameter> and
|
|
<parameter>length</parameter> from the
|
|
<parameter>input</parameter> array, and replaces them with the
|
|
elements of the <parameter>replacement</parameter> array, if
|
|
supplied. It returns an array containing the extracted elements.
|
|
</para>
|
|
<para>
|
|
If <parameter>offset</parameter> is positive then the start of
|
|
removed portion is at that offset from the beginning of the
|
|
<parameter>input</parameter> array. If
|
|
<parameter>offset</parameter> is negative then it starts that far
|
|
from the end of the <parameter>input</parameter> array.
|
|
</para>
|
|
<para>
|
|
If <parameter>length</parameter> is omitted, removes everything
|
|
from <parameter>offset</parameter> to the end of the array. If
|
|
<parameter>length</parameter> is specified and is positive, then
|
|
that many elements will be removed. If
|
|
<parameter>length</parameter> is specified and is negative then
|
|
the end of the removed portion will be that many elements from
|
|
the end of the array. Tip: to remove everything from
|
|
<parameter>offset</parameter> to the end of the array when
|
|
<parameter>replacement</parameter> is also specified, use
|
|
<literal>count($input)</literal> for
|
|
<parameter>length</parameter>.
|
|
</para>
|
|
<para>
|
|
If <parameter>replacement</parameter> array is specified, then
|
|
the removed elements are replaced with elements from this array.
|
|
If <parameter>offset</parameter> and
|
|
<parameter>length</parameter> are such that nothing is removed,
|
|
then the elements from the <parameter>replacement</parameter>
|
|
array are inserted in the place specified by the
|
|
<parameter>offset</parameter>. Tip: if the replacement is just
|
|
one element it is not necessary to put <literal>array()</literal>
|
|
around it, unless the element is an array itself.
|
|
</para>
|
|
<para>
|
|
The following equivalences hold:
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
array_push ($input, $x, $y) array_splice ($input, count ($input), 0,
|
|
array ($x, $y))
|
|
array_pop ($input) array_splice ($input, -1)
|
|
array_shift ($input) array_splice ($input, 0, 1)
|
|
array_unshift ($input, $x, $y) array_splice ($input, 0, 0, array ($x, $y))
|
|
$a[$x] = $y array_splice ($input, $x, 1, $y)
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Returns the array consisting of removed elements.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_splice</function> examples</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$input = array ("red", "green", "blue", "yellow");
|
|
array_splice ($input, 2);
|
|
// $input is now array ("red", "green")
|
|
|
|
$input = array ("red", "green", "blue", "yellow");
|
|
array_splice ($input, 1, -1);
|
|
// $input is now array ("red", "yellow")
|
|
|
|
$input = array ("red", "green", "blue", "yellow");
|
|
array_splice ($input, 1, count($input), "orange");
|
|
// $input is now array ("red", "orange")
|
|
|
|
$input = array ("red", "green", "blue", "yellow");
|
|
array_splice ($input, -1, 1, array("black", "maroon"));
|
|
// $input is now array ("red", "green",
|
|
// "blue", "black", "maroon")
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>array_slice</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-sum">
|
|
<refnamediv>
|
|
<refname>array_sum</refname>
|
|
<refpurpose>
|
|
Calculate the sum of values in an array.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>array_sum</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_sum</function> returns the sum of values
|
|
in an array as an integer or float.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_sum</function> examples</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$a = array(2, 4, 6, 8);
|
|
echo "sum(a) = ".array_sum($a)."\n";
|
|
|
|
$b = array("a"=>1.2,"b"=>2.3,"c"=>3.4);
|
|
echo "sum(b) = ".array_sum($b)."\n";
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The printout of the program above will be:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
sum(a) = 20
|
|
sum(b) = 6.9
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
PHP versions prior to 4.0.6 modified the passed array
|
|
itself and converted strings to numbers (which most
|
|
of the time converted them to zero, depending on
|
|
their value).
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-unique">
|
|
<refnamediv>
|
|
<refname>array_unique</refname>
|
|
<refpurpose>Removes duplicate values from an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_unique</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_unique</function> takes input
|
|
<parameter>array</parameter> and returns a new array
|
|
without duplicate values.
|
|
</para>
|
|
<para>
|
|
Note that keys are preserved. <function>array_unique</function> sorts
|
|
the values treated as string at first, then will keep the first key
|
|
encountered for every value, and ignore all following keys. It does not
|
|
mean that the key of the first related value from the unsorted
|
|
<parameter>array</parameter> will be kept.
|
|
</para>
|
|
<note>
|
|
<simpara>
|
|
Two elements are considered equal if and only if
|
|
<literal>(string) $elem1 === (string) $elem2</literal>. In words:
|
|
when the string representation is the same.
|
|
<!-- TODO: example of it... -->
|
|
</simpara>
|
|
<simpara>
|
|
The first element will be used.
|
|
</simpara>
|
|
</note>
|
|
<warning>
|
|
<simpara>
|
|
This was broken in PHP 4.0.4!
|
|
<!-- TODO: when exactly was this broken?... -->
|
|
</simpara>
|
|
</warning>
|
|
<para>
|
|
<example>
|
|
<title><function>array_unique</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$input = array ("a" => "green", "red", "b" => "green", "blue", "red");
|
|
$result = array_unique ($input);
|
|
print_r($result);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This will output:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[b] => green
|
|
[1] => blue
|
|
[2] => red
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_unique</function> and types</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$input = array (4,"4","3",4,3,"3");
|
|
$result = array_unique ($input);
|
|
var_dump($result);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The printout of the program above will be (PHP 4.0.6):
|
|
<screen role="php">
|
|
<![CDATA[
|
|
array(2) {
|
|
[3]=>
|
|
int(4)
|
|
[4]=>
|
|
int(3)
|
|
}
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-unshift">
|
|
<refnamediv>
|
|
<refname>array_unshift</refname>
|
|
<refpurpose>
|
|
Prepend one or more elements to the beginning of array
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>array_unshift</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
<methodparam><type>mixed</type><parameter>var</parameter></methodparam>
|
|
<methodparam choice="opt"><type>mixed</type><parameter>
|
|
...
|
|
</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_unshift</function> prepends passed elements to
|
|
the front of the <parameter>array</parameter>. Note that the list
|
|
of elements is prepended as a whole, so that the prepended
|
|
elements stay in the same order.
|
|
</para>
|
|
<para>
|
|
Returns the new number of elements in the
|
|
<parameter>array</parameter>.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_unshift</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$queue = array ("orange", "banana");
|
|
array_unshift ($queue, "apple", "raspberry");
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This would result in <varname>$queue</varname> having the
|
|
following elements:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[0] => apple
|
|
[1] => raspberry
|
|
[2] => orange
|
|
[3] => banana
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>array_shift</function>,
|
|
<function>array_push</function>, and
|
|
<function>array_pop</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-values">
|
|
<refnamediv>
|
|
<refname>array_values</refname>
|
|
<refpurpose>Return all the values of an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>array_values</methodname>
|
|
<methodparam><type>array</type><parameter>input</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>array_values</function> returns all the values from the
|
|
<parameter>input</parameter> array.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>array_values</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$array = array ("size" => "XL", "color" => "gold");
|
|
print_r(array_values ($array));
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This will output:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[0] => XL
|
|
[1] => gold
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
This function was added to PHP 4, below is an implementation for
|
|
those still using PHP 3.
|
|
<example>
|
|
<title>
|
|
Implementation of <function>array_values</function> for PHP 3
|
|
users
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function array_values ($arr) {
|
|
$t = array();
|
|
while (list($k, $v) = each ($arr)) {
|
|
$t[] = $v;
|
|
}
|
|
return $t;
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</note>
|
|
<para>
|
|
See also <function>array_keys</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-walk">
|
|
<refnamediv>
|
|
<refname>array_walk</refname>
|
|
<refpurpose>
|
|
Apply a user function to every member of an array
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>array_walk</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>func</parameter></methodparam>
|
|
<methodparam choice="opt"><type>mixed</type><parameter>userdata</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<simpara>
|
|
Applies the user-defined function named by <parameter>func</parameter>
|
|
to each element of <parameter>array</parameter>.
|
|
<parameter>func</parameter> will be passed array value as the
|
|
first parameter and array key as the second parameter. If
|
|
<parameter>userdata</parameter> is supplied, it will be passed as
|
|
the third parameter to the user function. <parameter>func</parameter>
|
|
must be a user-defined function, and can't be a native PHP function.
|
|
Thus, you can't use <function>array_walk</function> straight with
|
|
<function>str2lower</function>, you must build a user-defined function
|
|
with it first, and pass this function as argument.
|
|
</simpara>
|
|
¬e.func-callback;
|
|
<simpara>
|
|
If <parameter>func</parameter> requires more than two or three
|
|
arguments, depending on <parameter>userdata</parameter>, a
|
|
warning will be generated each time
|
|
<function>array_walk</function> calls
|
|
<parameter>func</parameter>. These warnings may be suppressed by
|
|
prepending the '@' sign to the <function>array_walk</function>
|
|
call, or by using <function>error_reporting</function>.
|
|
</simpara>
|
|
<note>
|
|
<para>
|
|
If <parameter>func</parameter> needs to be working with the
|
|
actual values of the array, specify that the first parameter of
|
|
<parameter>func</parameter> should be passed by reference. Then
|
|
any changes made to those elements will be made in the array
|
|
itself.
|
|
</para>
|
|
<para>
|
|
Modifying the array from inside <parameter>func</parameter>
|
|
may cause unpredictable behavior.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
Passing the key and userdata to <parameter>func</parameter> was
|
|
added in 4.0.
|
|
</para>
|
|
<para>
|
|
In PHP 4 <function>reset</function> needs to be called as
|
|
necessary since <function>array_walk</function> does not reset
|
|
the array by default.
|
|
</para>
|
|
<para>
|
|
Users may not change the array itself from the callback
|
|
function. e.g. Add/delete element, unset the array that
|
|
<function>array_walk</function> is applied to. If the array is
|
|
changed, the behavior of this function is undefined.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<example>
|
|
<title><function>array_walk</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple");
|
|
|
|
function test_alter (&$item1, $key, $prefix) {
|
|
$item1 = "$prefix: $item1";
|
|
}
|
|
|
|
function test_print ($item2, $key) {
|
|
echo "$key. $item2<br>\n";
|
|
}
|
|
echo "Before ...:\n";
|
|
array_walk ($fruits, 'test_print');
|
|
reset ($fruits);
|
|
array_walk ($fruits, 'test_alter', 'fruit');
|
|
echo "... and after:\n";
|
|
reset ($fruits);
|
|
array_walk ($fruits, 'test_print');
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The printout of the program above will be:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Before ...:
|
|
d. lemon
|
|
a. orange
|
|
b. banana
|
|
c. apple
|
|
... and after:
|
|
d. fruit: lemon
|
|
a. fruit: orange
|
|
b. fruit: banana
|
|
c. fruit: apple
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<simpara>
|
|
See also <function>each</function> and <function>list</function>.
|
|
</simpara>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.arsort">
|
|
<refnamediv>
|
|
<refname>arsort</refname>
|
|
<refpurpose>
|
|
Sort an array in reverse order and maintain index association
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>arsort</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>sort_flags</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function sorts an array such that array indices maintain
|
|
their correlation with the array elements they are associated
|
|
with. This is used mainly when sorting associative arrays where
|
|
the actual element order is significant.
|
|
</para>
|
|
<example>
|
|
<title><function>arsort</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple");
|
|
arsort ($fruits);
|
|
reset ($fruits);
|
|
while (list ($key, $val) = each ($fruits)) {
|
|
echo "$key = $val\n";
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This example would display:
|
|
<screen>
|
|
<![CDATA[
|
|
a = orange
|
|
d = lemon
|
|
b = banana
|
|
c = apple
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
<para>
|
|
The fruits have been sorted in reverse alphabetical order, and
|
|
the index associated with each element has been maintained.
|
|
</para>
|
|
<para>
|
|
You may modify the behavior of the sort using the optional
|
|
parameter <parameter>sort_flags</parameter>, for details
|
|
see <function>sort</function>.
|
|
</para>
|
|
<para>
|
|
See also <function>asort</function>, <function>rsort</function>,
|
|
<function>ksort</function>, and <function>sort</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.asort">
|
|
<refnamediv>
|
|
<refname>asort</refname>
|
|
<refpurpose>Sort an array and maintain index association</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>asort</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>sort_flags</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function sorts an array such that array indices maintain
|
|
their correlation with the array elements they are associated
|
|
with. This is used mainly when sorting associative arrays where
|
|
the actual element order is significant.
|
|
</para>
|
|
<example>
|
|
<title><function>asort</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple");
|
|
asort ($fruits);
|
|
reset ($fruits);
|
|
while (list ($key, $val) = each ($fruits)) {
|
|
echo "$key = $val\n";
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This example would display:
|
|
<screen>
|
|
<![CDATA[
|
|
c = apple
|
|
b = banana
|
|
d = lemon
|
|
a = orange
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
<para>
|
|
The fruits have been sorted in alphabetical order, and the index
|
|
associated with each element has been maintained.
|
|
</para>
|
|
<para>
|
|
You may modify the behavior of the sort using the optional
|
|
parameter <parameter>sort_flags</parameter>, for details
|
|
see <function>sort</function>.
|
|
</para>
|
|
<para>
|
|
See also <function>arsort</function>, <function>rsort</function>,
|
|
<function>ksort</function>, and <function>sort</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.compact">
|
|
<refnamediv>
|
|
<refname>compact</refname>
|
|
<refpurpose>
|
|
Create array containing variables and their values
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>compact</methodname>
|
|
<methodparam><type>mixed</type><parameter>varname</parameter></methodparam>
|
|
<methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>compact</function> takes a variable number of
|
|
parameters. Each parameter can be either a string containing the
|
|
name of the variable, or an array of variable names. The array
|
|
can contain other arrays of variable names inside it;
|
|
<function>compact</function> handles it recursively.
|
|
</para>
|
|
<para>
|
|
For each of these, <function>compact</function> looks for a
|
|
variable with that name in the current symbol table and adds it
|
|
to the output array such that the variable name becomes the key
|
|
and the contents of the variable become the value for that key.
|
|
In short, it does the opposite of <function>extract</function>.
|
|
It returns the output array with all the variables added to it.
|
|
</para>
|
|
<para>
|
|
Any strings that are not set will simply be skipped.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>compact</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$city = "San Francisco";
|
|
$state = "CA";
|
|
$event = "SIGGRAPH";
|
|
|
|
$location_vars = array ("city", "state");
|
|
|
|
$result = compact ("event", "nothing_here", $location_vars);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
After this, <varname>$result</varname> will be:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[event] => SIGGRAPH
|
|
[city] => San Francisco
|
|
[state] => CA
|
|
)
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>extract</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.count">
|
|
<refnamediv>
|
|
<refname>count</refname>
|
|
<refpurpose>Count elements in a variable</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>count</methodname>
|
|
<methodparam><type>mixed</type><parameter>var</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Returns the number of elements in <parameter>var</parameter>,
|
|
which is typically an <type>array</type> (since anything else will have
|
|
one element).
|
|
</para>
|
|
<para>
|
|
If <parameter>var</parameter> is not an array, <literal>1</literal> will
|
|
be returned (exception: <literal>count(&null;)</literal> equals
|
|
<literal>0</literal>).
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
<function>count</function> may return 0 for a variable that
|
|
isn't set, but it may also return 0 for a variable that has
|
|
been initialized with an empty array. Use
|
|
<function>isset</function> to test if a variable is set.
|
|
</para>
|
|
</warning>
|
|
<para>
|
|
Please see the <link linkend="language.types.array">Arrays</link>
|
|
section of the manual for a detailed explanation of how arrays
|
|
are implemented and used in PHP.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>count</function> example</title>
|
|
<programlisting role="php">
|
|
<!-- TODO: examples about count(null), count(false), count(object).. -->
|
|
<![CDATA[
|
|
$a[0] = 1;
|
|
$a[1] = 3;
|
|
$a[2] = 5;
|
|
$result = count ($a);
|
|
// $result == 3
|
|
|
|
$b[0] = 7;
|
|
$b[5] = 9;
|
|
$b[10] = 11;
|
|
$result = count ($b);
|
|
// $result == 3;
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
The <function>sizeof</function> function is an
|
|
<link linkend="aliases">alias</link> for <function>count</function>.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
See also <function>is_array</function>,
|
|
<function>isset</function>, and
|
|
<function>strlen</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.current">
|
|
<refnamediv>
|
|
<refname>current</refname>
|
|
<refpurpose>Return the current element in an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>current</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Every array has an internal pointer to its "current" element,
|
|
which is initialized to the first element inserted into the
|
|
array.
|
|
</para>
|
|
<para>
|
|
The <function>current</function> function simply returns the
|
|
array element that's currently being pointed by the internal
|
|
pointer. It does not move the pointer in any way. If the
|
|
internal pointer points beyond the end of the elements list,
|
|
<function>current</function> returns &false;.
|
|
<warning>
|
|
<para>
|
|
If the array contains empty elements (0 or "", the empty
|
|
string) then this function will return &false;
|
|
for these elements as well. This makes it impossible to
|
|
determine if you are really at the end of the list in such
|
|
an array using <function>current</function>. To properly
|
|
traverse an array that may contain empty elements, use the
|
|
<function>each</function> function.
|
|
</para>
|
|
</warning>
|
|
</para>
|
|
<para>
|
|
See also <function>end</function>, <function>next</function>,
|
|
<function>prev</function>, and <function>reset</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.each">
|
|
<refnamediv>
|
|
<refname>each</refname>
|
|
<refpurpose>
|
|
Return the current key and value pair from an array and advance
|
|
the array cursor
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>each</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Returns the current key and value pair from the array
|
|
<parameter>array</parameter> and advances the array cursor. This
|
|
pair is returned in a four-element array, with the keys
|
|
<emphasis>0</emphasis>, <emphasis>1</emphasis>,
|
|
<emphasis>key</emphasis>, and
|
|
<emphasis>value</emphasis>. Elements <emphasis>0</emphasis> and
|
|
<emphasis>key</emphasis> contain the key name of the array
|
|
element, and <emphasis>1</emphasis> and
|
|
<emphasis>value</emphasis> contain the data.
|
|
</para>
|
|
<para>
|
|
If the internal pointer for the array points past the end of the
|
|
array contents, <function>each</function> returns
|
|
&false;.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>each</function> examples</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$foo = array ("bob", "fred", "jussi", "jouni", "egon", "marliese");
|
|
$bar = each ($foo);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
<varname>$bar</varname> now contains the following key/value
|
|
pairs:
|
|
<itemizedlist spacing="compact">
|
|
<listitem><simpara>0 => 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">
|
|
<![CDATA[
|
|
$foo = array ("Robert" => "Bob", "Seppo" => "Sepi");
|
|
$bar = each ($foo);
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
<varname>$bar</varname> now contains the following key/value
|
|
pairs:
|
|
<itemizedlist spacing="compact">
|
|
<listitem><simpara>0 => '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">
|
|
<![CDATA[
|
|
echo "Values submitted via POST method:<br>";
|
|
reset ($HTTP_POST_VARS);
|
|
while (list ($key, $val) = each ($HTTP_POST_VARS)) {
|
|
echo "$key => $val<br>";
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
After <function>each</function> has executed, the array cursor
|
|
will be left on the next element of the array, or on the last
|
|
element if it hits the end of the array. You have to use
|
|
<function>reset</function> if you want to traverse the array
|
|
again using each.
|
|
</para>
|
|
<para>
|
|
See also <function>key</function>, <function>list</function>,
|
|
<function>current</function>, <function>reset</function>,
|
|
<function>next</function>, and <function>prev</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.end">
|
|
<refnamediv>
|
|
<refname>end</refname>
|
|
<refpurpose>
|
|
Set the internal pointer of an array to its last element
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>end</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>end</function> advances <parameter>array</parameter>'s
|
|
internal pointer to the last element, and returns that element.
|
|
</para>
|
|
<para>
|
|
See also <function>current</function>,
|
|
<function>each</function>,
|
|
<function>next</function>, and <function>reset</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.extract">
|
|
<refnamediv>
|
|
<refname>extract</refname>
|
|
<refpurpose>
|
|
Import variables into the current symbol table from an array
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>extract</methodname>
|
|
<methodparam><type>array</type><parameter>var_array</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>extract_type</parameter></methodparam>
|
|
<methodparam choice="opt"><type>string</type><parameter>prefix</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function is used to import variables from an array into the
|
|
current symbol table. It takes an associative array
|
|
<parameter>var_array</parameter> and treats keys as variable
|
|
names and values as variable values. For each key/value pair it
|
|
will create a variable in the current symbol table, subject to
|
|
<parameter>extract_type</parameter> and
|
|
<parameter>prefix</parameter> parameters.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Since version 4.0.5 this function returns the number of
|
|
variables extracted.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
EXTR_IF_EXISTS and EXTR_PREFIX_IF_EXISTS was introduced in version 4.2.0.
|
|
</para>
|
|
<para>
|
|
EXTR_REFS was introduced in version 4.3.0.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<function>extract</function> checks each key to see whether it
|
|
constitutes a valid variable name and also for collisions with
|
|
existing variables in the symbol table. The way invalid/numeric
|
|
keys and collisions are treated is determined by
|
|
<parameter>extract_type</parameter>. It can be one of the
|
|
following values:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>EXTR_OVERWRITE</term>
|
|
<listitem>
|
|
<simpara>
|
|
If there is a collision, overwrite the existing variable.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>EXTR_SKIP</term>
|
|
<listitem>
|
|
<simpara>
|
|
If there is a collision, don't overwrite the existing
|
|
variable.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>EXTR_PREFIX_SAME</term>
|
|
<listitem>
|
|
<simpara>If there is a collision, prefix the variable name with
|
|
<parameter>prefix</parameter>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>EXTR_PREFIX_ALL</term>
|
|
<listitem>
|
|
<simpara>
|
|
Prefix all variable names with
|
|
<parameter>prefix</parameter>. Since PHP 4.0.5 this includes
|
|
numeric ones as well.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>EXTR_PREFIX_INVALID</term>
|
|
<listitem>
|
|
<simpara>
|
|
Only prefix invalid/numeric variable names with
|
|
<parameter>prefix</parameter>. This flag was added in
|
|
PHP 4.0.5.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>EXTR_IF_EXISTS</term>
|
|
<listitem>
|
|
<simpara>
|
|
Only overwrite the variable if it already exists in the
|
|
current symbol table, otherwise do nothing. This is useful
|
|
for defining a list of valid variables and then extracting
|
|
only those variables you have defined out of $_REQUEST, for
|
|
example. This flag was added in PHP 4.2.0.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>EXTR_PREFIX_IF_EXISTS</term>
|
|
<listitem>
|
|
<simpara>
|
|
Only create prefixed variable names if the non-prefixed version
|
|
of the same variable exists in the current symbol table. This
|
|
flag was added in PHP 4.2.0.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
If <parameter>extract_type</parameter> is not specified, it is
|
|
assumed to be EXTR_OVERWRITE.
|
|
</para>
|
|
<para>
|
|
Note that <parameter>prefix</parameter> is only required if
|
|
<parameter>extract_type</parameter> is EXTR_PREFIX_SAME,
|
|
EXTR_PREFIX_ALL, EXTR_PREFIX_INVALID or EXTR_PREFIX_IF_EXISTS. If
|
|
the prefixed result is not a valid variable name, it is not
|
|
imported into the symbol table.
|
|
</para>
|
|
<para>
|
|
An additional EXTR_REFS flag can be OR'ed together with the
|
|
<parameter>extract_type</parameter>. If it is set, the variables are
|
|
imported into the symbol table as references, and modifying any of them
|
|
will also modify the entries in the <parameter>var_array</parameter>.
|
|
</para>
|
|
<para>
|
|
<function>extract</function> returns the number of variables
|
|
successfully imported into the symbol table.
|
|
</para>
|
|
<para>
|
|
A possible use for extract is to import into the symbol table
|
|
variables contained in an associative array returned by
|
|
<function>wddx_deserialize</function>.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>extract</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
/* Suppose that $var_array is an array returned from
|
|
wddx_deserialize */
|
|
|
|
$size = "large";
|
|
$var_array = array ("color" => "blue",
|
|
"size" => "medium",
|
|
"shape" => "sphere");
|
|
extract ($var_array, EXTR_PREFIX_SAME, "wddx");
|
|
|
|
print "$color, $size, $shape, $wddx_size\n";
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
The above example will produce:
|
|
<programlisting>
|
|
<![CDATA[
|
|
blue, large, sphere, medium
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
The <varname>$size</varname> wasn't overwritten, because we
|
|
specified EXTR_PREFIX_SAME, which resulted in
|
|
<varname>$wddx_size</varname> being created. If EXTR_SKIP was
|
|
specified, then $wddx_size wouldn't even have been created.
|
|
EXTR_OVERWRITE would have caused <varname>$size</varname> to have
|
|
value "medium", and EXTR_PREFIX_ALL would result in new variables
|
|
being named <varname>$wddx_color</varname>,
|
|
<varname>$wddx_size</varname>, and
|
|
<varname>$wddx_shape</varname>.
|
|
</para>
|
|
<para>
|
|
You must use an associative array, a numerically indexed array
|
|
will not produce results unless you use EXTR_PREFIX_ALL or
|
|
EXTR_PREFIX_INVALID.
|
|
</para>
|
|
<para>
|
|
See also <function>compact</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.in-array">
|
|
<refnamediv>
|
|
<refname>in_array</refname>
|
|
<refpurpose>Return &true; if a value exists in an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>bool</type><methodname>in_array</methodname>
|
|
<methodparam><type>mixed</type><parameter>needle</parameter></methodparam>
|
|
<methodparam><type>array</type><parameter>haystack</parameter></methodparam>
|
|
<methodparam choice="opt"><type>bool</type><parameter>strict</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Searches <parameter>haystack</parameter> for
|
|
<parameter>needle</parameter> and returns &true;
|
|
if it is found in the array, &false; otherwise.
|
|
</para>
|
|
<para>
|
|
If the third parameter <parameter>strict</parameter> is set to
|
|
&true; then the <function>in_array</function> function
|
|
will also check the <link linkend="language.types">types</link> of
|
|
the <parameter>needle</parameter> in the <parameter>haystack</parameter>.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
If <parameter>needle</parameter> is a string, the comparison is done in
|
|
a case-sensitive manner.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
In PHP versions before 4.2.0 <parameter>needle</parameter> was not
|
|
allowed to be an array.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<example>
|
|
<title><function>in_array</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$os = array ("Mac", "NT", "Irix", "Linux");
|
|
if (in_array ("Irix", $os)) {
|
|
print "Got Irix";
|
|
}
|
|
if (in_array ("mac", $os)) {
|
|
print "Got mac";
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The second condition fails because <function>in_array</function>
|
|
is case-sensitive, so the program above will display:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
Got Irix
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>in_array</function> with strict example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$a = array('1.10', 12.4, 1.13);
|
|
|
|
if (in_array('12.4', $a, TRUE))
|
|
echo "'12.4' found with strict check\n";
|
|
if (in_array(1.13, $a, TRUE))
|
|
echo "1.13 found with strict check\n";
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This will display:
|
|
<screen role="php">
|
|
<![CDATA[
|
|
1.13 found with strict check
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>in_array</function> with an array as needle</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$a = array(array('p', 'h'), array('p', 'r'), 'o');
|
|
|
|
if (in_array(array ('p', 'h'), $a))
|
|
echo "'ph' is found\n";
|
|
if (in_array(array ('f', 'i'), $a))
|
|
echo "'fi' is not found\n";
|
|
if (in_array('o', $a))
|
|
echo "'o' is found\n";
|
|
?>
|
|
|
|
// This will output:
|
|
|
|
'ph' is found
|
|
'o' is found
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>array_search</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.array-search">
|
|
<refnamediv>
|
|
<refname>array_search</refname>
|
|
<refpurpose>
|
|
Searches the array for a given value and returns the
|
|
corresponding key if successful
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>array_search</methodname>
|
|
<methodparam><type>mixed</type><parameter>needle</parameter></methodparam>
|
|
<methodparam><type>array</type><parameter>haystack</parameter></methodparam>
|
|
<methodparam choice="opt"><type>bool</type><parameter>strict</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Searches <parameter>haystack</parameter> for
|
|
<parameter>needle</parameter> and returns the key if it is found in
|
|
the array, &false; otherwise.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Prior to PHP 4.2.0, <function>array_search</function> returns
|
|
<constant>NULL</constant> on failure instead of &false;.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
If the optional third parameter <parameter>strict</parameter> is set to
|
|
&true; then the <function>array_search</function>
|
|
will also check the types of the <parameter>needle</parameter>
|
|
in the <parameter>haystack</parameter>.
|
|
</para>
|
|
&return.falseproblem;
|
|
<para>
|
|
See also <function>array_keys</function> and <function>in_array</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.key">
|
|
<refnamediv>
|
|
<refname>key</refname>
|
|
<refpurpose>Fetch a key from an associative array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>key</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>key</function> returns the index element of the
|
|
current array position.
|
|
</para>
|
|
<para>
|
|
See also <function>current</function> and <function>next</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.krsort">
|
|
<refnamediv>
|
|
<refname>krsort</refname>
|
|
<refpurpose>Sort an array by key in reverse order</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>krsort</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>sort_flags</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Sorts an array by key in reverse order, maintaining key to data
|
|
correlations. This is useful mainly for associative arrays.
|
|
<example>
|
|
<title><function>krsort</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple");
|
|
krsort ($fruits);
|
|
reset ($fruits);
|
|
while (list ($key, $val) = each ($fruits)) {
|
|
echo "$key = $val\n";
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
This example would display:
|
|
</para>
|
|
<para>
|
|
<screen>
|
|
<![CDATA[
|
|
d = lemon
|
|
c = apple
|
|
b = banana
|
|
a = orange
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
You may modify the behavior of the sort using the optional
|
|
parameter <parameter>sort_flags</parameter>, for details
|
|
see <function>sort</function>.
|
|
</para>
|
|
<simpara>
|
|
See also <function>asort</function>, <function>arsort</function>,
|
|
<function>ksort</function>, <function>sort</function>,
|
|
<function>natsort</function>, and <function>rsort</function>.
|
|
</simpara>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.ksort">
|
|
<refnamediv>
|
|
<refname>ksort</refname>
|
|
<refpurpose>Sort an array by key</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>ksort</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>sort_flags</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Sorts an array by key, maintaining key to data correlations. This
|
|
is useful mainly for associative arrays.
|
|
<example>
|
|
<title><function>ksort</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$fruits = array ("d"=>"lemon", "a"=>"orange", "b"=>"banana", "c"=>"apple");
|
|
ksort ($fruits);
|
|
reset ($fruits);
|
|
while (list ($key, $val) = each ($fruits)) {
|
|
echo "$key = $val\n";
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
This example would display:
|
|
</para>
|
|
<para>
|
|
<screen>
|
|
<![CDATA[
|
|
a = orange
|
|
b = banana
|
|
c = apple
|
|
d = lemon
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
You may modify the behavior of the sort using the optional
|
|
parameter <parameter>sort_flags</parameter>, for details
|
|
see <function>sort</function>.
|
|
</para>
|
|
<simpara>
|
|
See also <function>asort</function>, <function>arsort</function>,
|
|
<function>krsort</function>, <function>uksort</function>,
|
|
<function>sort</function>, <function>natsort</function>, and
|
|
<function>rsort</function>.
|
|
</simpara>
|
|
<note>
|
|
<para>
|
|
The second parameter was added in PHP 4.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.list">
|
|
<refnamediv>
|
|
<refname>list</refname>
|
|
<refpurpose>
|
|
Assign variables as if they were an array
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>list</methodname>
|
|
<methodparam rep="repeat"><type>mixed</type><parameter>...</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Like <function>array</function>, this is not really a function,
|
|
but a language construct. <function>list</function> is used to
|
|
assign a list of variables in one operation.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
<function>list</function> only works on numerical arrays and assumes
|
|
the numerical indices start at 0.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<example>
|
|
<title><function>list</function> examples</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$info = array('coffee', 'brown', 'caffeine');
|
|
|
|
// Listing all the variables
|
|
list($drink, $color, $power) = $info;
|
|
print "$drink is $color and $power makes it special.\n";
|
|
|
|
// Listing some of them
|
|
list($drink, , $power) = $info;
|
|
print "$drink has $power.\n";
|
|
|
|
// Or let's skip to only the third one
|
|
list( , , $power) = $info;
|
|
print "I need $power!\n";
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>An example use of <function>list</function></title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<table>
|
|
<tr>
|
|
<th>Employee name</th>
|
|
<th>Salary</th>
|
|
</tr>
|
|
|
|
<?php
|
|
|
|
$result = mysql_query ("SELECT id, name, salary FROM employees",$conn);
|
|
while (list ($id, $name, $salary) = mysql_fetch_row ($result)) {
|
|
print (" <tr>\n".
|
|
" <td><a href=\"info.php?id=$id\">$name</a></td>\n".
|
|
" <td>$salary</td>\n".
|
|
" </tr>\n");
|
|
}
|
|
|
|
?>
|
|
|
|
</table>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>each</function>, <function>array</function>
|
|
and <function>extract</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.natsort">
|
|
<refnamediv>
|
|
<refname>natsort</refname>
|
|
<refpurpose>
|
|
Sort an array using a "natural order" algorithm
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>natsort</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function implements a sort algorithm that orders
|
|
alphanumeric strings in the way a human being would. This is
|
|
described as a "natural ordering". An example of the difference
|
|
between this algorithm and the regular computer string sorting
|
|
algorithms (used in <function>sort</function>) can be seen below:
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>natsort</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$array1 = $array2 = array ("img12.png", "img10.png", "img2.png", "img1.png");
|
|
|
|
sort($array1);
|
|
echo "Standard sorting\n";
|
|
print_r($array1);
|
|
|
|
natsort($array2);
|
|
echo "\nNatural order sorting\n";
|
|
print_r($array2);
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
The code above will generate the following output:
|
|
</para>
|
|
<para>
|
|
<screen>
|
|
<![CDATA[
|
|
Standard sorting
|
|
Array
|
|
(
|
|
[0] => img1.png
|
|
[1] => img10.png
|
|
[2] => img12.png
|
|
[3] => img2.png
|
|
)
|
|
|
|
Natural order sorting
|
|
Array
|
|
(
|
|
[3] => img1.png
|
|
[2] => img2.png
|
|
[1] => img10.png
|
|
[0] => img12.png
|
|
)
|
|
]]>
|
|
</screen>
|
|
For more information see: Martin Pool's <ulink
|
|
url="&url.strnatcmp;">Natural Order String Comparison</ulink>
|
|
page.
|
|
</para>
|
|
<para>
|
|
See also <function>natcasesort</function>,
|
|
<function>strnatcmp</function>, and
|
|
<function>strnatcasecmp</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.natcasesort">
|
|
<refnamediv>
|
|
<refname>natcasesort</refname>
|
|
<refpurpose>
|
|
Sort an array using a case insensitive "natural order" algorithm
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>natcasesort</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function implements a sort algorithm that orders
|
|
alphanumeric strings in the way a human being would. This is
|
|
described as a "natural ordering".
|
|
</para>
|
|
<para>
|
|
<function>natcasesort</function> is a case insensitive version of
|
|
<function>natsort</function>. See <function>natsort</function>
|
|
for an example of the difference between this algorithm and the
|
|
regular computer string sorting algorithms.
|
|
</para>
|
|
<para>
|
|
For more information see: Martin Pool's <ulink
|
|
url="&url.strnatcmp;">Natural Order String Comparison</ulink>
|
|
page.
|
|
</para>
|
|
<para>
|
|
See also <function>sort</function>,
|
|
<function>natsort</function>,
|
|
<function>strnatcmp</function>, and
|
|
<function>strnatcasecmp</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.next">
|
|
<refnamediv>
|
|
<refname>next</refname>
|
|
<refpurpose>
|
|
Advance the internal array pointer of an array
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>next</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Returns the array element in the next place that's pointed by the
|
|
internal array pointer, or &false; if
|
|
there are no more elements.
|
|
</para>
|
|
<para>
|
|
<function>next</function> behaves like
|
|
<function>current</function>, with one difference. It advances
|
|
the internal array pointer one place forward before returning the
|
|
element. That means it returns the next array element and
|
|
advances the internal array pointer by one. If advancing the
|
|
internal array pointer results in going beyond the end of the
|
|
element list, <function>next</function> returns &false;.
|
|
<warning>
|
|
<para>
|
|
If the array contains empty elements, or elements that have a key
|
|
value of 0 then this function will return &false;
|
|
for these elements as well. To properly traverse an array which
|
|
may contain empty elements or elements with key values of 0 see the
|
|
<function>each</function> function.
|
|
</para>
|
|
</warning>
|
|
</para>
|
|
<para>
|
|
See also
|
|
<function>current</function>, <function>end</function>,
|
|
<function>prev</function>, and <function>reset</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.pos">
|
|
<refnamediv>
|
|
<refname>pos</refname>
|
|
<refpurpose>Get the current element from an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>pos</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<simpara>
|
|
This is an <link linkend="aliases">alias</link>
|
|
for <function>current</function>.
|
|
</simpara>
|
|
<para>
|
|
See also
|
|
<function>end</function>, <function>next</function>,
|
|
<function>prev</function>, and <function>reset</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.prev">
|
|
<refnamediv>
|
|
<refname>prev</refname>
|
|
<refpurpose>Rewind the internal array pointer</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>prev</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Returns the array element in the previous place that's pointed by
|
|
the internal array pointer, or &false; if there are no more
|
|
elements.
|
|
<warning>
|
|
<para>
|
|
If the array contains empty elements then this function will
|
|
return &false; for these elements as well.
|
|
To properly traverse an array which may contain empty elements
|
|
see the <function>each</function> function.
|
|
</para>
|
|
</warning>
|
|
</para>
|
|
<para>
|
|
<function>prev</function> behaves just like
|
|
<function>next</function>, except it rewinds the internal array
|
|
pointer one place instead of advancing it.
|
|
</para>
|
|
<para>
|
|
See also <function>current</function>, <function>end</function>,
|
|
<function>next</function>, and <function>reset</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.range">
|
|
<refnamediv>
|
|
<refname>range</refname>
|
|
<refpurpose>
|
|
Create an array containing a range of elements
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>range</methodname>
|
|
<methodparam><type>mixed</type><parameter>low</parameter></methodparam>
|
|
<methodparam><type>mixed</type><parameter>high</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>range</function> returns an array of elements from
|
|
<parameter>low</parameter> to <parameter>high</parameter>,
|
|
inclusive. If low > high, the sequence will be from high to low.
|
|
</para>
|
|
<example>
|
|
<title><function>range</function> examples</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
foreach(range(0, 9) as $number) {
|
|
echo $number;
|
|
}
|
|
foreach(range('a', 'z') as $letter) {
|
|
echo $letter;
|
|
}
|
|
foreach(range('z', 'a') as $letter) {
|
|
echo $letter;
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<note>
|
|
<para>
|
|
Prior to version 4.1.0 the <function>range</function> function
|
|
only generated incrementing integer arrays. Support for
|
|
character sequences and decrementing arrays was added in 4.1.0.
|
|
</para>
|
|
<example>
|
|
<title>Simulating decrementing ranges and character sequences</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
# array_reverse can be used to flip the order of a range
|
|
foreach(array_reverse(range(0,9)) as $number) {
|
|
echo $number;
|
|
}
|
|
|
|
# array_map() can be used to turn integers into characters using chr()
|
|
foreach(array_map('chr', range(ord('a'),ord('z'))) as $character) {
|
|
echo $character;
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</note>
|
|
<para>
|
|
See <function>shuffle</function> for another example of its use.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.reset">
|
|
<refnamediv>
|
|
<refname>reset</refname>
|
|
<refpurpose>
|
|
Set the internal pointer of an array to its first element
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname>reset</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>reset</function> rewinds <parameter>array</parameter>'s
|
|
internal pointer to the first element.
|
|
</para>
|
|
<para>
|
|
<function>reset</function> returns the value of the first array
|
|
element.
|
|
</para>
|
|
<para>
|
|
See also <function>current</function>,
|
|
<function>each</function>, <function>next</function>,
|
|
and <function>prev</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.rsort">
|
|
<refnamediv>
|
|
<refname>rsort</refname>
|
|
<refpurpose>Sort an array in reverse order</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>rsort</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>sort_flags</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function sorts an array in reverse order (highest to lowest).
|
|
<example>
|
|
<title><function>rsort</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$fruits = array ("lemon", "orange", "banana", "apple");
|
|
rsort ($fruits);
|
|
reset ($fruits);
|
|
while (list ($key, $val) = each ($fruits)) {
|
|
echo "$key = $val\n";
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
This example would display:
|
|
</para>
|
|
<para>
|
|
<screen>
|
|
<![CDATA[
|
|
0 = orange
|
|
1 = lemon
|
|
2 = banana
|
|
3 = apple
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
The fruits have been sorted in reverse alphabetical order.
|
|
</para>
|
|
<para>
|
|
You may modify the behavior of the sort using the optional
|
|
parameter <parameter>sort_flags</parameter>, for details
|
|
see <function>sort</function>.
|
|
</para>
|
|
<para>
|
|
See also <function>arsort</function>,
|
|
<function>asort</function>, <function>ksort</function>,
|
|
<function>sort</function>, and <function>usort</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.shuffle">
|
|
<refnamediv>
|
|
<refname>shuffle</refname>
|
|
<refpurpose>Shuffle an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>shuffle</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function shuffles (randomizes the order of the elements in)
|
|
an array. You must use <function>srand</function> to seed this
|
|
function.
|
|
<example>
|
|
<title><function>shuffle</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$numbers = range (1,20);
|
|
srand ((float)microtime()*1000000);
|
|
shuffle ($numbers);
|
|
while (list (, $number) = each ($numbers)) {
|
|
echo "$number ";
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>arsort</function>, <function>asort</function>,
|
|
<function>ksort</function>, <function>rsort</function>,
|
|
<function>sort</function>, and <function>usort</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.sizeof">
|
|
<refnamediv>
|
|
<refname>sizeof</refname>
|
|
<refpurpose>Get the number of elements in variable</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>sizeof</methodname>
|
|
<methodparam><type>mixed</type><parameter>var</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
The <function>sizeof</function> function is an
|
|
<link linkend="aliases">alias</link> for <function>count</function>.
|
|
</para>
|
|
<para>
|
|
See also <function>count</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.sort">
|
|
<refnamediv>
|
|
<refname>sort</refname>
|
|
<refpurpose>Sort an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>sort</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>sort_flags</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function sorts an array. Elements will be arranged from
|
|
lowest to highest when this function has completed.
|
|
<example>
|
|
<title><function>sort</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$fruits = array ("lemon", "orange", "banana", "apple");
|
|
sort ($fruits);
|
|
reset ($fruits);
|
|
while (list ($key, $val) = each ($fruits)) {
|
|
echo "fruits[".$key."] = ".$val."\n";
|
|
}
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
This example would display:
|
|
</para>
|
|
<para>
|
|
<screen>
|
|
<![CDATA[
|
|
fruits[0] = apple
|
|
fruits[1] = banana
|
|
fruits[2] = lemon
|
|
fruits[3] = orange
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
The fruits have been sorted in alphabetical order.
|
|
</para>
|
|
<para>
|
|
The optional second parameter <parameter>sort_flags</parameter>
|
|
may be used to modify the sorting behavior using these values:
|
|
</para>
|
|
<para>
|
|
Sorting type flags:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>SORT_REGULAR - compare items normally</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>SORT_NUMERIC - compare items numerically</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>SORT_STRING - compare items as strings</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
See also <function>arsort</function>,
|
|
<function>asort</function>, <function>ksort</function>,
|
|
<function>natsort</function>, <function>natcasesort</function>,
|
|
<function>rsort</function>, <function>usort</function>,
|
|
<function>array_multisort</function>, and
|
|
<function>uksort</function>.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
The second parameter was added in PHP 4.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.uasort">
|
|
<refnamediv>
|
|
<refname>uasort</refname>
|
|
<refpurpose>
|
|
Sort an array with a user-defined comparison function and
|
|
maintain index association
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>uasort</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
<methodparam><type>function</type><parameter>cmp_function</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function sorts an array such that array indices maintain
|
|
their correlation with the array elements they are associated
|
|
with. This is used mainly when sorting associative arrays where
|
|
the actual element order is significant. The comparison function
|
|
is user-defined.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Please see <function>usort</function> and
|
|
<function>uksort</function> for examples of user-defined
|
|
comparison functions.
|
|
</para>
|
|
</note>
|
|
¬e.func-callback;
|
|
<para>
|
|
See also <function>usort</function>, <function>uksort</function>,
|
|
<function>sort</function>, <function>asort</function>,
|
|
<function>arsort</function>, <function>ksort</function>,
|
|
and <function>rsort</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.uksort">
|
|
<refnamediv>
|
|
<refname>uksort</refname>
|
|
<refpurpose>
|
|
Sort an array by keys using a user-defined comparison function
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>uksort</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
<methodparam><type>function</type><parameter>cmp_function</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function will sort the keys of an array using a
|
|
user-supplied comparison function. If the array you wish to sort
|
|
needs to be sorted by some non-trivial criteria, you should use
|
|
this function.
|
|
</para>
|
|
<example>
|
|
<title><function>uksort</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function cmp ($a, $b) {
|
|
if ($a == $b) return 0;
|
|
return ($a > $b) ? -1 : 1;
|
|
}
|
|
|
|
$a = array (4 => "four", 3 => "three", 20 => "twenty", 10 => "ten");
|
|
|
|
uksort ($a, "cmp");
|
|
|
|
while (list ($key, $value) = each ($a)) {
|
|
echo "$key: $value\n";
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
This example would display:
|
|
</para>
|
|
<para>
|
|
<screen>
|
|
<![CDATA[
|
|
20: twenty
|
|
10: ten
|
|
4: four
|
|
3: three
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
¬e.func-callback;
|
|
<para>
|
|
See also <function>usort</function>, <function>uasort</function>,
|
|
<function>sort</function>, <function>asort</function>,
|
|
<function>arsort</function>, <function>ksort</function>,
|
|
<function>natsort</function>, and <function>rsort</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.usort">
|
|
<refnamediv>
|
|
<refname>usort</refname>
|
|
<refpurpose>
|
|
Sort an array by values using a user-defined comparison function
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>usort</methodname>
|
|
<methodparam><type>array</type><parameter>array</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>cmp_function</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function will sort an array by its values using a
|
|
user-supplied comparison function. If the array you wish to sort
|
|
needs to be sorted by some non-trivial criteria, you should use
|
|
this function.
|
|
</para>
|
|
<para>
|
|
The comparison function must return an integer less than, equal
|
|
to, or greater than zero if the first argument is considered to
|
|
be respectively less than, equal to, or greater than the
|
|
second. If two members compare as equal, their order in the
|
|
sorted array is undefined.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>usort</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function cmp ($a, $b) {
|
|
if ($a == $b) return 0;
|
|
return ($a > $b) ? -1 : 1;
|
|
}
|
|
|
|
$a = array (3, 2, 5, 6, 1);
|
|
|
|
usort ($a, "cmp");
|
|
|
|
while (list ($key, $value) = each ($a)) {
|
|
echo "$key: $value\n";
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
This example would display:
|
|
</para>
|
|
<para>
|
|
<screen>
|
|
<![CDATA[
|
|
0: 6
|
|
1: 5
|
|
2: 3
|
|
3: 2
|
|
4: 1
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Obviously in this trivial case the <function>rsort</function>
|
|
function would be more appropriate.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<example>
|
|
<title>
|
|
<function>usort</function> example using multi-dimensional array
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function cmp ($a, $b) {
|
|
return strcmp($a["fruit"], $b["fruit"]);
|
|
}
|
|
|
|
$fruits[0]["fruit"] = "lemons";
|
|
$fruits[1]["fruit"] = "apples";
|
|
$fruits[2]["fruit"] = "grapes";
|
|
|
|
usort($fruits, "cmp");
|
|
|
|
while (list ($key, $value) = each ($fruits)) {
|
|
echo "\$fruits[$key]: " . $value["fruit"] . "\n";
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
When sorting a multi-dimensional array, $a and $b contain
|
|
references to the first index of the array.
|
|
</para>
|
|
<para>
|
|
This example would display:
|
|
</para>
|
|
<para>
|
|
<screen>
|
|
<![CDATA[
|
|
$fruits[0]: apples
|
|
$fruits[1]: grapes
|
|
$fruits[2]: lemons
|
|
]]>
|
|
</screen>
|
|
</para>
|
|
¬e.func-callback;
|
|
<para>
|
|
<example>
|
|
<title>
|
|
<function>usort</function> example using a member function of an object
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
class TestObj {
|
|
var $name;
|
|
|
|
function TestObj($name)
|
|
{
|
|
$this->name = $name;
|
|
}
|
|
|
|
/* This is the static comparing function: */
|
|
function cmp_obj($a, $b)
|
|
{
|
|
$al = strtolower($a->name);
|
|
$bl = strtolower($b->name);
|
|
if ($al == $bl) return 0;
|
|
return ($al > $bl) ? +1 : -1;
|
|
}
|
|
}
|
|
|
|
$a[] = new TestObj("c");
|
|
$a[] = new TestObj("b");
|
|
$a[] = new TestObj("d");
|
|
|
|
uasort($a, array ("TestObj", "cmp_obj"));
|
|
|
|
foreach ($a as $item) {
|
|
print $item->name."\n";
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
This example would display:
|
|
</para>
|
|
<para>
|
|
<screen>
|
|
b
|
|
c
|
|
d
|
|
</screen>
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
The underlying quicksort function in some C libraries (such as
|
|
on Solaris systems) may cause PHP to crash if the comparison
|
|
function does not return consistent values.
|
|
</para>
|
|
</warning>
|
|
<para>
|
|
See also <function>uasort</function>,
|
|
<function>uksort</function>, <function>sort</function>,
|
|
<function>asort</function>,
|
|
<function>arsort</function>,<function>ksort</function>,
|
|
<function>natsort</function>, and <function>rsort</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
</reference>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|
|
|