sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Switch to new doc style

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@249444 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Mehdi Achour 2007-12-30 19:17:05 +00:00
parent e72eeb989f
commit 885d702e25
22 changed files with 1323 additions and 478 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

80
reference/array/functions/array-reverse.xml
View file

@ -1,24 +1,76 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.62 -->
<!-- $Revision: 1.12 $ -->
<refentry xml:id="function.array-reverse" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_reverse</refname>
<refpurpose>Return an array with elements in reverse order</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<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;.
Takes an input <parameter>array</parameter> and returns a new array with
the order of the elements reversed.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
The input array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>preserve_keys</parameter></term>
<listitem>
<para>
If set to &true; keys are preserved.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the reversed array.
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>4.0.3</entry>
<entry>
The <parameter>preserve_keys</parameter> parameter was added.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>array_reverse</function> example</title>
@ -66,13 +118,13 @@ Array
</screen>
</example>
</para>
<note>
<para>
The second parameter was added in PHP 4.0.3.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>array_flip</function>.
<simplelist>
<member><function>array_flip</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

121
reference/array/functions/array-search.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.12 $ -->
<refentry xml:id="function.array-search" xmlns="http://docbook.org/ns/docbook">
<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>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>array_search</methodname>
<methodparam><type>mixed</type><parameter>needle</parameter></methodparam>
@ -15,35 +14,89 @@
<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.
Searches <parameter>haystack</parameter> for <parameter>needle</parameter>.
</para>
<note>
<para>
If <parameter>needle</parameter> is a string, the comparison is done
in a case-sensitive manner.
</para>
</note>
<note>
<para>
Prior to PHP 4.2.0, <function>array_search</function> returns
&null; on failure instead of &false;.
</para>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<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>.
<variablelist>
<varlistentry>
<term><parameter>needle</parameter></term>
<listitem>
<para>
The searched value.
</para>
<note>
<para>
If <parameter>needle</parameter> is a string, the comparison is done
in a case-sensitive manner.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>haystack</parameter></term>
<listitem>
<para>
The array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>strict</parameter></term>
<listitem>
<para>
If the third parameter <parameter>strict</parameter> is set to &true;
then the <function>array_search</function> function will also check the
<link linkend="language.types">types</link> of the
<parameter>needle</parameter> in the <parameter>haystack</parameter>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the key for <parameter>needle</parameter> if it is found in the
array, &false; otherwise.
</para>
<para>
If <parameter>needle</parameter> is found in
<parameter>haystack</parameter> more than once, the first matching key
is returned. To return the keys for all matching values, use
<function>array_keys</function> with the optional
If <parameter>needle</parameter> is found in <parameter>haystack</parameter>
more than once, the first matching key is returned. To return the keys for
all matching values, use <function>array_keys</function> with the optional
<parameter>search_value</parameter> parameter instead.
</para>
&return.falseproblem;
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>4.2.0</entry>
<entry>
Prior to PHP 4.2.0, <function>array_search</function> returns &null;
on failure instead of &false;.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>array_search</function> example</title>
@ -59,12 +112,16 @@ $key = array_search('red', $array); // $key = 1;
</programlisting>
</example>
</para>
&return.falseproblem;
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>array_keys</function>,
<function>array_values</function>,
<function>array_key_exists</function>, and
<function>in_array</function>.
<simplelist>
<member><function>array_keys</function></member>
<member><function>array_values</function></member>
<member><function>array_key_exists</function></member>
<member><function>in_array</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

76
reference/array/functions/array-shift.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.14 $ -->
<refentry xml:id="function.array-shift" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_shift</refname>
<refpurpose>Shift an element off the beginning of array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>array_shift</methodname>
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
@ -17,15 +16,38 @@
<parameter>array</parameter> off and returns it, shortening the
<parameter>array</parameter> by one element and moving everything
down. All numerical array keys will be modified to start counting from zero
while literal keys won't be touched. If <parameter>array</parameter> is empty
(or is not an array), &null; will be returned.
while literal keys won't be touched.
</para>
&array.resetspointer;
<example>
<title><function>array_shift</function> example</title>
<programlisting role="php">
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
The input array.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the shifted value, or &null; if <parameter>array</parameter> is
empty or is not an array.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>array_shift</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$stack = array("orange", "banana", "apple", "raspberry");
@ -33,11 +55,9 @@ $fruit = array_shift($stack);
print_r($stack);
?>
]]>
</programlisting>
<para>
This would result in <varname>$stack</varname> having 3 elements left:
</para>
<screen role="php">
</programlisting>
&example.outputs;
<screen role="php">
<![CDATA[
Array
(
@ -46,16 +66,22 @@ Array
[2] => raspberry
)
]]>
</screen>
<para>
and <literal>orange</literal> will be assigned to
<varname>$fruit</varname>.
</para>
</example>
</screen>
<para>
and <literal>orange</literal> will be assigned to
<varname>$fruit</varname>.
</para>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>array_unshift</function>,
<function>array_push</function>, and
<function>array_pop</function>.
<simplelist>
<member><function>array_unshift</function></member>
<member><function>array_push</function></member>
<member><function>array_pop</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

106
reference/array/functions/array-slice.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.15 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.16 $ -->
<refentry xml:id="function.array-slice" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_slice</refname>
<refpurpose>Extract a slice of the array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>array_slice</methodname>
<methodparam><type>array</type><parameter>array</parameter></methodparam>
@ -21,26 +20,88 @@
<parameter>offset</parameter> and <parameter>length</parameter>
parameters.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
If <parameter>offset</parameter> is non-negative, 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>.
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
The input array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
If <parameter>offset</parameter> is non-negative, 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>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>length</parameter></term>
<listitem>
<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>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>preserve_keys</parameter></term>
<listitem>
<para>
Note that <function>array_slice</function> will reorder and reset the
array indices by default. You can change this behaviour by setting
<parameter>preserve_keys</parameter> to &true;.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<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>.
Returns the slice.
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
Note that <function>array_slice</function> will reorder and reset the
array indices by default. Since PHP 5.0.2, you can change this
behaviour by setting <parameter>preserve_keys</parameter> to &true;.
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>5.0.2</entry>
<entry>
The optional <parameter>preserve_keys</parameter> parameter was added.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>array_slice</function> examples</title>
@ -76,9 +137,14 @@ Array
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>array_splice</function> and
<function>unset</function>.
<simplelist>
<member><function>array_splice</function></member>
<member><function>unset</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

101
reference/array/functions/array-udiff-assoc.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.14 -->
<!-- $Revision: 1.12 $ -->
<refentry xml:id="function.array-udiff-assoc" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_udiff_assoc</refname>
<refpurpose>Computes the difference of arrays with additional index check, compares data by a callback function</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>array_udiff_assoc</methodname>
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
@ -15,6 +14,57 @@
<methodparam choice="opt"><type>array</type><parameter> ...</parameter></methodparam>
<methodparam><type>callback</type><parameter>data_compare_func</parameter></methodparam>
</methodsynopsis>
<para>
Computes the difference of arrays with additional index check, compares
data by a callback function.
</para>
<note>
<simpara>
Please note that this function only checks one dimension of a n-dimensional
array. Of course you can check deeper dimensions by using, for example,
<literal>array_udiff_assoc($array1[0], $array2[0], "some_comparison_func");</literal>.
</simpara>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array1</parameter></term>
<listitem>
<para>
The first array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>array2</parameter></term>
<listitem>
<para>
The second array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data_compare_func</parameter></term>
<listitem>
<para>
The callback comparison function.
</para>
<para>
The user supplied callback function is used for comparison.
It 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.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<function>array_udiff_assoc</function> returns an <type>array</type>
containing all the values from <parameter>array1</parameter>
@ -26,6 +76,9 @@
<function>array_diff_assoc</function> which uses internal function for
comparison.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>array_udiff_assoc</function> example</title>
@ -83,32 +136,22 @@ Array
pair is present in both arrays and thus it is not in the ouput from the
function.
</simpara>
<simpara>
For comparison is used the user supplied callback function.
It 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.
</simpara>
<note>
<simpara>
Please note that this function only checks one dimension of a n-dimensional
array. Of course you can check deeper dimensions by using, for example,
<literal>array_udiff_assoc($array1[0], $array2[0], "some_comparison_func");</literal>.
</simpara>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also
<function>array_diff</function>,
<function>array_diff_assoc</function>,
<function>array_diff_uassoc</function>,
<function>array_udiff</function>,
<function>array_udiff_uassoc</function>,
<function>array_intersect</function>,
<function>array_intersect_assoc</function>,
<function>array_uintersect</function>,
<function>array_uintersect_assoc</function> and
<function>array_uintersect_uassoc</function>.
<simplelist>
<member><function>array_diff</function></member>
<member><function>array_diff_assoc</function></member>
<member><function>array_diff_uassoc</function></member>
<member><function>array_udiff</function></member>
<member><function>array_udiff_uassoc</function></member>
<member><function>array_intersect</function></member>
<member><function>array_intersect_assoc</function></member>
<member><function>array_uintersect</function></member>
<member><function>array_uintersect_assoc</function></member>
<member><function>array_uintersect_uassoc</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

81
reference/array/functions/array-uintersect-assoc.xml
View file

@ -1,12 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<refentry xml:id="function.array-uintersect-assoc" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_uintersect_assoc</refname>
<refpurpose>Computes the intersection of arrays with additional index check, compares data by a callback function</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>array_uintersect_assoc</methodname>
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
@ -15,12 +15,59 @@
<methodparam><type>callback</type><parameter>data_compare_func</parameter></methodparam>
</methodsynopsis>
<para>
<function>array_uintersect_assoc</function> returns an array
containing all the values of <parameter>array1</parameter>
that are present in all the arguments. Note that the keys are used in
the comparison unlike in <function>array_uintersect</function>.
Computes the intersection of arrays with additional index check, compares
data by a callback function.
</para>
<para>
Note that the keys are used in the comparison unlike in
<function>array_uintersect</function>.
The data is compared by using a callback function.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array1</parameter></term>
<listitem>
<para>
The first array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>array2</parameter></term>
<listitem>
<para>
The second array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data_compare_func</parameter></term>
<listitem>
<para>
For comparison is used the user supplied callback function.
It 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.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an array containing all the values of
<parameter>array1</parameter> that are present in all the arguments.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>array_uintersect_assoc</function> example</title>
@ -45,18 +92,16 @@ Array
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
For comparison is used the user supplied callback function.
It 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.
</para>
<para>
See also <function>array_uintersect</function>,
<function>array_intersect_assoc</function>,
<function>array_intersect_uassoc</function> and
<function>array_uintersect_uassoc</function>.
<simplelist>
<member><function>array_uintersect</function></member>
<member><function>array_intersect_assoc</function></member>
<member><function>array_intersect_uassoc</function></member>
<member><function>array_uintersect_uassoc</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

34
reference/array/functions/array-unique.xml
View file

@ -1,20 +1,18 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.16 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.17 $ -->
<refentry xml:id="function.array-unique" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_unique</refname>
<refpurpose>Removes duplicate values from an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<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
Takes an input <parameter>array</parameter> and returns a new array
without duplicate values.
</para>
<para>
@ -34,6 +32,30 @@
The first element will be used.
</simpara>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
The input array.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the filtered array.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>array_unique</function> example</title>

78
reference/array/functions/asort.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.14 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.15 $ -->
<refentry xml:id="function.asort" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>asort</refname>
<refpurpose>Sort an array and maintain index association</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>asort</methodname>
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
@ -19,12 +18,44 @@
with. This is used mainly when sorting associative arrays where
the actual element order is significant.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
The input array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>sort_flags</parameter></term>
<listitem>
<para>
You may modify the behavior of the sort using the optional
parameter <parameter>sort_flags</parameter>, for details
see <function>sort</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
<example>
<title><function>asort</function> example</title>
<programlisting role="php">
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>asort</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$fruits = array("d" => "lemon", "a" => "orange", "b" => "banana", "c" => "apple");
@ -34,29 +65,32 @@ foreach ($fruits as $key => $val) {
}
?>
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
c = apple
b = banana
d = lemon
a = orange
]]>
</screen>
</example>
<para>
The fruits have been sorted in alphabetical order, and the index
associated with each element has been maintained.
</screen>
<para>
The fruits have been sorted in alphabetical order, and the index
associated with each element has been maintained.
</para>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<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>.
<simplelist>
<member><function>arsort</function></member>
<member><function>sort</function></member>
<member><function>ksort</function></member>
<member><function>rsort</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

115
reference/array/functions/count.xml
View file

@ -1,22 +1,19 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.19 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.20 $ -->
<refentry xml:id="function.count" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>count</refname>
<refpurpose>Count elements in an array, or properties in an object</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>count</methodname>
<methodparam><type>mixed</type><parameter>var</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>mode</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.
Counts elements in an array, or properties in an object.
</para>
<para>
For objects, if you have
@ -26,6 +23,47 @@
<function>count</function>, which returns the return value for the
<function>count</function> function.
</para>
<para>
Please see the <link linkend="language.types.array">Array</link>
section of the manual for a detailed explanation of how arrays
are implemented and used in PHP.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>var</parameter></term>
<listitem>
<para>
The array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
If the optional <parameter>mode</parameter> parameter is set to
<constant>COUNT_RECURSIVE</constant> (or 1), <function>count</function>
will recursively count the array. This is particularly useful for
counting all the elements of a multidimensional array. The default
value for <parameter>mode</parameter> is <literal>0</literal>.
<function>count</function> does not detect infinite recursion.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<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 or an object with
implemented <literal>Countable</literal> interface,
@ -33,33 +71,39 @@
There is one exception, if <parameter>var</parameter> is &null;,
<literal>0</literal> will be returned.
</para>
<note>
<simpara>
The optional <parameter>mode</parameter> parameter is available as of
PHP 4.2.0.
</simpara>
</note>
<para>
If the optional <parameter>mode</parameter> parameter is set to
<constant>COUNT_RECURSIVE</constant> (or 1), <function>count</function>
will recursively count the array. This is particularly useful for
counting all the elements of a multidimensional array. The default
value for <parameter>mode</parameter> is <literal>0</literal>.
<function>count</function> does not detect infinite recursion.
</para>
<caution>
<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.
<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>
</caution>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
Please see the <link linkend="language.types.array">Array</link>
section of the manual for a detailed explanation of how arrays
are implemented and used in PHP.
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>4.2.0</entry>
<entry>
The optional <parameter>mode</parameter> parameter was added.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>count</function> example</title>
@ -90,9 +134,7 @@ $result = count(false);
</para>
<para>
<example>
<title>
Recursive <function>count</function> example (PHP &gt;= 4.2.0)
</title>
<title>Recursive <function>count</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
@ -110,10 +152,15 @@ echo count($food); // output 2
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>is_array</function>,
<function>isset</function>, and
<function>strlen</function>.
<simplelist>
<member><function>is_array</function></member>
<member><function>isset</function></member>
<member><function>strlen</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

63
reference/array/functions/current.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.14 $ -->
<refentry xml:id="function.current" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>current</refname>
<refpurpose>Return the current element in an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>current</methodname>
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
@ -17,6 +16,24 @@
which is initialized to the first element inserted into the
array.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
The array.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The <function>current</function> function simply returns the
value of the array element that's currently being pointed to by the
@ -24,17 +41,10 @@
internal pointer points beyond the end of the elements list,
<function>current</function> returns &false;.
</para>
&return.falseproblem;
<note>
<simpara>
You won't be able to distinguish the end of an array from a
<type>boolean</type> &false; element. To properly traverse an array
which may contain &false; elements, see the <function>each</function>
function.
</simpara>
</note>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Example use of <function>current</function> and friends</title>
@ -53,10 +63,29 @@ $mode = current($transport); // $mode = 'plane';
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<simpara>
You won't be able to distinguish the end of an array from a
<type>boolean</type> &false; element. To properly traverse an array
which may contain &false; elements, see the <function>each</function>
function.
</simpara>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>end</function>, <function>key</function>,
<function>next</function>, <function>prev</function>,
<function>reset</function>, and <function>each</function>.
<simplelist>
<member><function>end</function></member>
<member><function>key</function></member>
<member><function>each</function></member>
<member><function>prev</function></member>
<member><function>reset</function></member>
<member><function>next</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

76
reference/array/functions/each.xml
View file

@ -1,33 +1,62 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.19 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.20 $ -->
<refentry xml:id="function.each" xmlns="http://docbook.org/ns/docbook">
<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>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>each</methodname>
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
</methodsynopsis>
<para>
Return the current key and value pair from an array and advance the array
cursor.
</para>
<para>
After <function>each</function> has executed, the array cursor
will be left on the next element of the array, or past 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>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
The input array.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<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
<literal>0</literal>, <literal>1</literal>,
<literal>key</literal>, and
<literal>value</literal>. Elements <literal>0</literal> and
<literal>key</literal> contain the key name of the array
element, and <literal>1</literal> and
<literal>value</literal> contain the data.
<parameter>array</parameter>. This pair is returned in a four-element
array, with the keys <literal>0</literal>, <literal>1</literal>,
<literal>key</literal>, and <literal>value</literal>. Elements
<literal>0</literal> and <literal>key</literal> contain the key name of
the array element, and <literal>1</literal> and <literal>value</literal>
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>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>each</function> examples</title>
@ -113,13 +142,6 @@ c => cranberry
</screen>
</example>
</para>
<para>
After <function>each</function> has executed, the array cursor
will be left on the next element of the array, or past 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>
<caution>
<para>
Because assigning an array to another variable resets the original
@ -128,11 +150,19 @@ c => cranberry
loop.
</para>
</caution>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>key</function>, <function>list</function>,
<function>current</function>, <function>reset</function>,
<function>next</function>, <function>prev</function>, and
<link linkend="control-structures.foreach">foreach</link>.
<simplelist>
<member><function>key</function></member>
<member><function>list</function></member>
<member><function>current</function></member>
<member><function>reset</function></member>
<member><function>next</function></member>
<member><function>prev</function></member>
<member><link linkend="control-structures.foreach">foreach</link></member>
</simplelist>
</para>
</refsect1>
</refentry>

3
reference/array/functions/end.xml
View file

@ -1,6 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.15 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.16 $ -->
<refentry xml:id="function.end" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>end</refname>

109
reference/array/functions/in-array.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.14 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.56 -->
<!-- $Revision: 1.15 $ -->
<refentry xml:id="function.in-array" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>in_array</refname>
<refpurpose>Checks if a value exists in an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>in_array</methodname>
<methodparam><type>mixed</type><parameter>needle</parameter></methodparam>
@ -15,28 +14,81 @@
<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.
Searches <parameter>haystack</parameter> for <parameter>needle</parameter>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<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>.
<variablelist>
<varlistentry>
<term><parameter>needle</parameter></term>
<listitem>
<para>
The searched value.
</para>
<note>
<para>
If <parameter>needle</parameter> is a string, the comparison is done
in a case-sensitive manner.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>haystack</parameter></term>
<listitem>
<para>
The array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>strict</parameter></term>
<listitem>
<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>
</listitem>
</varlistentry>
</variablelist>
</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>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns &true; if <parameter>needle</parameter> is found in the array,
&false; otherwise.
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>4.2.0</entry>
<entry>
<parameter>needle</parameter> may now be an array.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>in_array</function> example</title>
@ -121,10 +173,15 @@ if (in_array('o', $a)) {
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>array_search</function>,
<function>array_key_exists</function>, and
<function>isset</function>.
<simplelist>
<member><function>array_search</function></member>
<member><function>isset</function></member>
<member><function>array_key_exists</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

91
reference/array/functions/ksort.xml
View file

@ -1,25 +1,78 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.14 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.15 $ -->
<refentry xml:id="function.ksort" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>ksort</refname>
<refpurpose>Sort an array by key</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>ksort</methodname>
<methodparam><type>array</type><parameter role="reference">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.
Sorts an array by key, maintaining key to data correlations. This is
useful mainly for associative arrays.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
The input array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>sort_flags</parameter></term>
<listitem>
<para>
You may modify the behavior of the sort using the optional
parameter <parameter>sort_flags</parameter>, for details
see <function>sort</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>4.0.0</entry>
<entry>
The optional <parameter>sort_flags</parameter> parameter was added.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>ksort</function> example</title>
@ -45,22 +98,20 @@ d = lemon
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
You may modify the behavior of the sort using the optional
parameter <parameter>sort_flags</parameter>, for details
see <function>sort</function>.
<simplelist>
<member><function>asort</function></member>
<member><function>arsort</function></member>
<member><function>krsort</function></member>
<member><function>uksort</function></member>
<member><function>sort</function></member>
<member><function>natsort</function></member>
<member><function>rsort</function></member>
</simplelist>
</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>

76
reference/array/functions/list.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.17 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.18 $ -->
<refentry xml:id="function.list" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>list</refname>
<refpurpose>Assign variables as if they were an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>list</methodname>
<methodparam><type>mixed</type><parameter>varname</parameter></methodparam>
@ -18,12 +17,30 @@
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>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>varname</parameter></term>
<listitem>
<para>
A variable.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.void;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>list</function> examples</title>
@ -81,16 +98,6 @@ while (list($id, $name, $salary) = mysql_fetch_row($result)) {
</programlisting>
</example>
</para>
<warning>
<para>
<function>list</function> assigns the values starting with the right-most
parameter. If you are using plain variables, you don't have to worry
about this. But if you are using arrays with indices you usually expect
the order of the indices in the array the same you wrote in the
<function>list</function> from left to right; which it isn't. It's
assigned in the reverse order.
</para>
</warning>
<para>
<example>
<title>Using <function>list</function> with array indices</title>
@ -125,9 +132,34 @@ array(3) {
</screen>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<warning>
<para>
<function>list</function> assigns the values starting with the right-most
parameter. If you are using plain variables, you don't have to worry
about this. But if you are using arrays with indices you usually expect
the order of the indices in the array the same you wrote in the
<function>list</function> from left to right; which it isn't. It's
assigned in the reverse order.
</para>
</warning>
<note>
<para>
<function>list</function> only works on numerical arrays and assumes
the numerical indices start at 0.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>each</function>, <function>array</function>
and <function>extract</function>.
<simplelist>
<member><function>each</function></member>
<member><function>array</function></member>
<member><function>extract</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

49
reference/array/functions/natcasesort.xml
View file

@ -1,29 +1,49 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.25 -->
<!-- $Revision: 1.12 $ -->
<refentry xml:id="function.natcasesort" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>natcasesort</refname>
<refpurpose>Sort an array using a case insensitive "natural order" algorithm</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>natcasesort</methodname>
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
</methodsynopsis>
<para>
<function>natcasesort</function> is a case insensitive version of
<function>natsort</function>.
</para>
<para>
This function implements a sort algorithm that orders
alphanumeric strings in the way a human being would while maintaining
key/value associations. This is described as a "natural ordering".
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
The input array.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
<para>
<function>natcasesort</function> is a case insensitive version of
<function>natsort</function>.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>natcasesort</function> example</title>
@ -75,11 +95,16 @@ Array
</para>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>sort</function>,
<function>natsort</function>,
<function>strnatcmp</function>, and
<function>strnatcasecmp</function>.
<simplelist>
<member><function>sort</function></member>
<member><function>natsort</function></member>
<member><function>strnatcmp</function></member>
<member><function>strnatcasecmp</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

50
reference/array/functions/natsort.xml
View file

@ -1,28 +1,47 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.15 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.25 -->
<!-- $Revision: 1.16 $ -->
<refentry xml:id="function.natsort" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>natsort</refname>
<refpurpose>Sort an array using a "natural order" algorithm</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>natsort</methodname>
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
</methodsynopsis>
<para>
This function implements a sort algorithm that orders
alphanumeric strings in the way a human being would while maintaining
key/value associations. 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:
This function implements a sort algorithm that orders alphanumeric strings
in the way a human being would while maintaining key/value associations.
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 in the example below.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
The input array.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>natsort</function> example</title>
@ -70,10 +89,15 @@ Array
</para>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>natcasesort</function>,
<function>strnatcmp</function>, and
<function>strnatcasecmp</function>.
<simplelist>
<member><function>natcasesort</function></member>
<member><function>strnatcmp</function></member>
<member><function>strnatcasecmp</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

41
reference/array/functions/next.xml
View file

@ -1,33 +1,31 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.12 $ -->
<refentry xml:id="function.next" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>next</refname>
<refpurpose>Advance the internal array pointer of an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>next</methodname>
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
</methodsynopsis>
<para>
Returns the array value in the next place that's pointed to 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 value. That means it returns the next array value 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;.
advances the internal array pointer by one.
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the array value in the next place that's pointed to by the
internal array pointer, or &false; if there are no more elements.
</para>
&return.falseproblem;
<note>
<simpara>
You won't be able to distinguish the end of an array from a
@ -36,6 +34,9 @@
function.
</simpara>
</note>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Example use of <function>next</function> and friends</title>
@ -53,11 +54,17 @@ $mode = end($transport); // $mode = 'plane';
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also
<function>current</function>, <function>end</function>,
<function>prev</function>, <function>reset</function>,
and <function>each</function>.
<simplelist>
<member><function>current</function></member>
<member><function>end</function></member>
<member><function>prev</function></member>
<member><function>reset</function></member>
<member><function>each</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

134
reference/array/functions/range.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.18 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.19 $ -->
<refentry xml:id="function.range" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>range</refname>
<refpurpose>Create an array containing a range of elements</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>range</methodname>
<methodparam><type>mixed</type><parameter>low</parameter></methodparam>
@ -15,22 +14,95 @@
<methodparam choice="opt"><type>number</type><parameter>step</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.
Create an array containing a range of elements.
</para>
<note>
<title>New parameter</title>
<simpara>
The optional <parameter>step</parameter> parameter was added in 5.0.0.
</simpara>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
If a <parameter>step</parameter> value is given, it will be used as the
increment between elements in the sequence. <parameter>step</parameter>
should be given as a positive number. If not specified,
<parameter>step</parameter> will default to 1.
<variablelist>
<varlistentry>
<term><parameter>low</parameter></term>
<listitem>
<para>
Low value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>high</parameter></term>
<listitem>
<para>
High value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>step</parameter></term>
<listitem>
<para>
If a <parameter>step</parameter> value is given, it will be used as the
increment between elements in the sequence. <parameter>step</parameter>
should be given as a positive number. If not specified,
<parameter>step</parameter> will default to 1.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
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>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>5.0.0</entry>
<entry>
The optional <parameter>step</parameter> parameter was added.
</entry>
</row>
<row>
<entry>4.1.0 to 4.3.2</entry>
<entry>
In PHP versions 4.1.0 through 4.3.2, <function>range</function> sees
numeric strings as strings and not integers. Instead, they will be
used for character sequences. For example, <literal>"4242"</literal>
is treated as <literal>"4"</literal>.
</entry>
</row>
<row>
<entry>4.1.0</entry>
<entry>
Prior to PHP 4.1.0, <function>range</function> only generated
incrementing integer arrays. Support for character sequences and
decrementing arrays was added in 4.1.0. Character sequence values
are limited to a length of one. If a length greater than one is
entered, only the first character is used.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>range</function> examples</title>
@ -62,27 +134,15 @@ foreach (range('c', 'a') as $letter) {
</programlisting>
</example>
</para>
<note>
<para>
Prior to PHP 4.1.0, <function>range</function> only generated
incrementing integer arrays. Support for character sequences and
decrementing arrays was added in 4.1.0. Character sequence values
are limited to a length of one. If a length greater than one is
entered, only the first character is used.
</para>
</note>
<caution>
<para>
In PHP versions 4.1.0 through 4.3.2, <function>range</function> sees
numeric strings as strings and not integers. Instead, they will be
used for character sequences. For example, <literal>"4242"</literal>
is treated as <literal>"4"</literal>.
</para>
</caution>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>shuffle</function>,
<function>array_fill</function>, and
<link linkend="control-structures.foreach">foreach</link>.
<simplelist>
<member><function>shuffle</function></member>
<member><function>array_fill</function></member>
<member><link linkend="control-structures.foreach">foreach</link></member>
</simplelist>
</para>
</refsect1>
</refentry>

142
reference/array/functions/sort.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.25 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.26 $ -->
<refentry xml:id="function.sort" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>sort</refname>
<refpurpose>Sort an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>sort</methodname>
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
@ -17,10 +16,85 @@
This function sorts an array. Elements will be arranged from
lowest to highest when this function has completed.
</para>
&note.no-key-association;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
The input array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>sort_flags</parameter></term>
<listitem>
<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><constant>SORT_REGULAR</constant> - compare items normally
(don't change types)</simpara>
</listitem>
<listitem>
<simpara><constant>SORT_NUMERIC</constant> - compare items numerically</simpara>
</listitem>
<listitem>
<simpara><constant>SORT_STRING</constant> - compare items as strings</simpara>
</listitem>
<listitem>
<simpara><constant>SORT_LOCALE_STRING</constant> - compare items as
strings, based on the current locale. Added in PHP 4.4.0 and 5.0.2.
Before PHP 6, it uses the system locale, which can be changed using
<function>setlocale</function>. Since PHP 6, you must use the
<function>i18n_loc_set_default</function> function.
</simpara>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>4.0.0</entry>
<entry>
The <parameter>sort_flags</parameter> parameter was added.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>sort</function> example</title>
@ -51,52 +125,32 @@ fruits[3] = orange
<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><constant>SORT_REGULAR</constant> - compare items normally
(don't change types)</simpara>
</listitem>
<listitem>
<simpara><constant>SORT_NUMERIC</constant> - compare items numerically</simpara>
</listitem>
<listitem>
<simpara><constant>SORT_STRING</constant> - compare items as strings</simpara>
</listitem>
<listitem>
<simpara><constant>SORT_LOCALE_STRING</constant> - compare items as
strings, based on the current locale. Added in PHP 4.4.0 and 5.0.2.
Before PHP 6, it uses the system locale, which can be changed using
<function>setlocale</function>. Since PHP 6, you must use the
<function>i18n_loc_set_default</function> function.
</simpara>
</listitem>
</itemizedlist>
</para>
<note>
<para>
The second parameter was added in PHP 4.
</para>
</note>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
&note.no-key-association;
<warning>
<simpara>
Be careful when sorting arrays with mixed types values because
<function>sort</function> can produce unpredictable results.
</simpara>
</warning>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>arsort</function>,
<function>asort</function>, <function>ksort</function>,
<function>krsort</function>,
<function>natsort</function>, <function>natcasesort</function>,
<function>rsort</function>, <function>usort</function>,
<function>array_multisort</function>, and
<function>uksort</function>.
<simplelist>
<member><function>arsort</function></member>
<member><function>asort</function></member>
<member><function>ksort</function></member>
<member><function>rsort</function></member>
<member><function>usort</function></member>
<member><function>uksort</function></member>
<member><function>array_multisort</function></member>
<member><function>krsort</function></member>
<member><function>natsort</function></member>
<member><function>natcasesort</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

65
reference/array/functions/uksort.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.21 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.22 $ -->
<refentry xml:id="function.uksort" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>uksort</refname>
<refpurpose>Sort an array by keys using a user-defined comparison function</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>uksort</methodname>
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
@ -19,17 +18,46 @@
needs to be sorted by some non-trivial criteria, you should use
this function.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
Function <parameter>cmp_function</parameter> should accept two
parameters which will be filled by pairs of <parameter>array</parameter> keys.
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.
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
The input array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>cmp_function</parameter></term>
<listitem>
<para>
The callback comparison function.
</para>
<para>
Function <parameter>cmp_function</parameter> should accept two
parameters which will be filled by pairs of <parameter>array</parameter> keys.
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.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>uksort</function> example</title>
@ -64,11 +92,20 @@ John: 1
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<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>.
<simplelist>
<member><function>usort</function></member>
<member><function>uasort</function></member>
<member><function>sort</function></member>
<member><function>asort</function></member>
<member><function>arsort</function></member>
<member><function>ksort</function></member>
<member><function>natsort</function></member>
<member><function>rsort</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

110
reference/array/functions/usort.xml
View file

@ -1,44 +1,86 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.26 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.27 $ -->
<refentry xml:id="function.usort" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>usort</refname>
<refpurpose>Sort an array by values using a user-defined comparison function</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>usort</methodname>
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
<methodparam><type>callback</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.
</para>
<para>
<note>
<para>
If two members compare as equal, their order in the sorted array is undefined.
Up to PHP 4.0.6 the user defined functions would keep the original order for
those elements, but with the new sort algorithm introduced with 4.1.0 this
is no longer the case as there is no solution to do so in an efficient way.
</para>
</note>
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>
<note>
<para>
If two members compare as equal, their order in the sorted array is undefined.
</para>
</note>
&note.no-key-association;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
The input array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>cmp_function</parameter></term>
<listitem>
<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.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>4.1.0</entry>
<entry>
A new sort algorithm was introduced. The <parameter>cmp_function</parameter>
doesn't keep the original order for elements comparing as equal.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>usort</function> example</title>
@ -120,7 +162,6 @@ $fruits[2]: lemons
</screen>
</example>
</para>
<para>
<example>
<title>
@ -171,13 +212,20 @@ d
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<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>.
<simplelist>
<member><function>uasort</function></member>
<member><function>uksort</function></member>
<member><function>sort</function></member>
<member><function>asort</function></member>
<member><function>arsort</function></member>
<member><function>ksort</function></member>
<member><function>natsort</function></member>
<member><function>rsort</function></member>
</simplelist>
</para>
</refsect1>
</refentry>