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@249451 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Mehdi Achour 2007-12-30 23:05:06 +00:00
parent 46d00a3a9c
commit c10971d592
13 changed files with 1010 additions and 556 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

56
reference/array/functions/array-merge.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.array-merge" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_merge</refname>
<refpurpose>Merge one or more arrays</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>array_merge</methodname>
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
@ -15,9 +14,9 @@
<methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam>
</methodsynopsis>
<para>
<function>array_merge</function> merges the elements of one or
more arrays together so that the values of one are appended to
the end of the previous one. It returns the resulting array.
Merges the elements of one 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
@ -30,6 +29,38 @@
If only one array is given and the array is numerically indexed, the
keys get reindexed in a continuous way.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array1</parameter></term>
<listitem>
<para>
Initial array to merge.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
Variable list of arrays to recursively merge.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the resulting array.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>array_merge</function> example</title>
@ -142,10 +173,15 @@ Array
</example>
</para>
</warning>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>array_merge_recursive</function>,
<function>array_combine</function> and
<link linkend="language.operators.array">array operators</link>.
<simplelist>
<member><function>array_merge_recursive</function></member>
<member><function>array_combine</function></member>
<member><link linkend="language.operators.array">array operators</link></member>
</simplelist>
</para>
</refsect1>
</refentry>

65
reference/array/functions/array-multisort.xml
View file

@ -1,24 +1,19 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.20 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.11 -->
<!-- $Revision: 1.21 $ -->
<refentry xml:id="function.array-multisort" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_multisort</refname>
<refpurpose>Sort multiple or multi-dimensional arrays</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<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>
<!-- Parameters don't need to be passed by reference -->
</methodsynopsis>
<para>
&return.success;
</para>
<para>
<function>array_multisort</function> can be used to sort several
arrays at once, or a multi-dimensional array by one or more
@ -28,51 +23,15 @@
Associative (<type>string</type>) keys will be maintained, but numeric
keys will be re-indexed.
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<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.
&return.success;
</para>
<para>
The argument structure of this function is a bit unusual, but
flexible. The 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><constant>SORT_ASC</constant> - Sort in ascending order</simpara>
</listitem>
<listitem>
<simpara><constant>SORT_DESC</constant> - Sort in descending order</simpara>
</listitem>
</itemizedlist>
</para>
<para>
Sorting type flags:
<itemizedlist>
<listitem>
<simpara><constant>SORT_REGULAR</constant> - Compare items normally</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>
</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 <constant>SORT_ASC</constant> and
<constant>SORT_REGULAR</constant> before each new array argument.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Sorting multiple arrays</title>
@ -112,7 +71,6 @@ array(4) {
</screen>
</example>
</para>
<para>
<example>
<title>Sorting multi-dimensional array</title>
@ -157,7 +115,6 @@ array(2) {
</screen>
</example>
</para>
<para>
<example>
<title>Sorting database results</title>
@ -238,7 +195,6 @@ volume | edition
</screen>
</example>
</para>
<para>
<example>
<title>Case insensitive sorting</title>
@ -278,7 +234,6 @@ Array
</screen>
</example>
</para>
</refsect1>
</refentry>

84
reference/array/functions/array-push.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-push" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_push</refname>
<refpurpose>Push one or more elements onto the end of array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>array_push</methodname>
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
@ -15,11 +14,10 @@
<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:
<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[
<?php
@ -29,9 +27,52 @@ $array[] = $var;
</programlisting>
repeated for each <parameter>var</parameter>.
</para>
<note>
<simpara>
If you use <function>array_push</function> to add one element to the
array it's better to use <literal>$array[] = </literal> because in that
way there is no overhead of calling a function.
</simpara>
</note>
<note>
<simpara>
<function>array_push</function> will raise a warning if the first
argument is not an array. This differs from the
<literal>$var[]</literal> behaviour where a new array is created.
</simpara>
</note>
</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>var</parameter></term>
<listitem>
<para>
The pushed value.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the new number of elements in the array.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>array_push</function> example</title>
@ -58,24 +99,15 @@ Array
</screen>
</example>
</para>
<note>
<simpara>
If you use <function>array_push</function> to add one element to the
array it's better to use <literal>$array[] = </literal> because in that
way there is no overhead of calling a function.
</simpara>
</note>
<note>
<simpara>
<function>array_push</function> will raise a warning if the first
argument is not an array. This differs from the
<literal>$var[]</literal> behaviour where a new array is created.
</simpara>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>array_pop</function>,
<function>array_shift</function>, and
<function>array_unshift</function>.
<simplelist>
<member><function>array_pop</function></member>
<member><function>array_shift</function></member>
<member><function>array_unshift</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

209
reference/array/functions/array-splice.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.14 -->
<!-- $Revision: 1.19 $ -->
<refentry xml:id="function.array-splice" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_splice</refname>
<refpurpose>Remove a portion of the array and replace it with something else</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>array_splice</methodname>
<methodparam><type>array</type><parameter role="reference">input</parameter></methodparam>
@ -16,101 +15,89 @@
<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.
Removes the elements designated by <parameter>offset</parameter> and
<parameter>length</parameter> from the <parameter>input</parameter> array,
and replaces them with the elements of the
<parameter>replacement</parameter> array, if supplied.
</para>
<para>
Note that numeric keys in <parameter>input</parameter> are not preserved.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<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.
<variablelist>
<varlistentry>
<term><parameter>input</parameter></term>
<listitem>
<para>
The input array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<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>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>length</parameter></term>
<listitem>
<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>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>replacement</parameter></term>
<listitem>
<para>
If <parameter>replacement</parameter> array is specified, then the
removed elements are replaced with elements from this array.
</para>
<para>
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>. Note that keys in
replacement array are not preserved.
</para>
<para>
If <parameter>replacement</parameter> is just one element it is
not necessary to put <literal>array()</literal>
around it, unless the element is an array itself.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<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>. Note that keys in replacement
array are not preserved.
If <parameter>replacement</parameter> 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 statements change the values of <varname>$input</varname>
the same way:
<table>
<title><function>array_splice</function> equivalents</title>
<tgroup cols="2">
<tbody>
<row>
<entry>
array_push($input, $x, $y)
</entry>
<entry>
array_splice($input, count($input), 0, array($x, $y))
</entry>
</row>
<row>
<entry>
array_pop($input)
</entry>
<entry>
array_splice($input, -1)
</entry>
</row>
<row>
<entry>
array_shift($input)
</entry>
<entry>
array_splice($input, 0, 1)
</entry>
</row>
<row>
<entry>
array_unshift($input, $x, $y)
</entry>
<entry>
array_splice($input, 0, 0, array($x, $y))
</entry>
</row>
<row>
<entry>
$input[$x] = $y // for arrays where key equals offset
</entry>
<entry>
array_splice($input, $x, 1, $y)
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
Returns the array consisting of removed elements.
Returns the array consisting of the extracted elements.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>array_splice</function> examples</title>
@ -144,9 +131,39 @@ array_splice($input, 3, 0, "purple");
</example>
</para>
<para>
See also <function>array_slice</function>,
<function>unset</function>, and
<function>array_merge</function>.
<example>
<title><function>array_splice</function> examples</title>
<para>
The following statements change the values of <varname>$input</varname>
the same way:
</para>
<programlisting role="php">
<![CDATA[
<?php
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));
$input[$x] = $y; // for arrays where key equals offset
array_splice($input, $x, 1, $y);
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>array_slice</function></member>
<member><function>unset</function></member>
<member><function>array_merge</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

123
reference/array/functions/array-udiff-uassoc.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.14 -->
<!-- $Revision: 1.14 $ -->
<refentry xml:id="function.array-udiff-uassoc" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_udiff_uassoc</refname>
<refpurpose>Computes the difference of arrays with additional index check, compares data and indexes by a callback function</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>array_udiff_uassoc</methodname>
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
@ -17,20 +16,79 @@
<methodparam><type>callback</type><parameter>key_compare_func</parameter></methodparam>
</methodsynopsis>
<para>
<function>array_udiff_uassoc</function> returns an <type>array</type>
containing all the values from <parameter>array1</parameter>
that are not present in any of the other arguments.
Computes the difference of arrays with additional index check, compares
data and indexes by a callback function.
</para>
<para>
Note that the keys are used in the comparison unlike
<function>array_diff</function> and <function>array_udiff</function>.
The comparison of arrays' data is performed by using an user-supplied
callback : <parameter>data_compare_func</parameter>. In this aspect
the behaviour is opposite to the behaviour of
<function>array_diff_assoc</function> which uses internal function for
comparison. The comparison of keys (indices) is done also by the
callback function <parameter>key_compare_func</parameter>. This
behaviour is unlike what <function>array_udiff_assoc</function> does, since
the latter compares the indices by using an internal 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>
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>
<para>
The comparison of arrays' data is performed by using an user-supplied
callback : <parameter>data_compare_func</parameter>. In this aspect
the behaviour is opposite to the behaviour of
<function>array_diff_assoc</function> which uses internal function for
comparison.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>key_compare_func</parameter></term>
<listitem>
<para>
The comparison of keys (indices) is done also by the callback function
<parameter>key_compare_func</parameter>. This behaviour is unlike what
<function>array_udiff_assoc</function> does, since the latter compares
the indices by using an internal function.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an <type>array</type> containing all the values from
<parameter>array1</parameter> that are not present in any of the other
arguments.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>array_udiff_uassoc</function> example</title>
@ -93,13 +151,9 @@ Array
pair is present in both arrays and thus it is not in the ouput from the
function. Keep in mind that you have to supply 2 callback functions.
</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>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<simpara>
Please note that this function only checks one dimension of a n-dimensional
@ -108,18 +162,21 @@ Array
"key_compare_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_assoc</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_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>

94
reference/array/functions/array-udiff.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.12 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.14 -->
<!-- $Revision: 1.13 $ -->
<refentry xml:id="function.array-udiff" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_udiff</refname>
<refpurpose>Computes the difference of arrays by using a callback function for data comparison</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>array_udiff</methodname>
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
@ -16,17 +15,57 @@
<methodparam><type>callback</type><parameter>data_compare_func</parameter></methodparam>
</methodsynopsis>
<para>
<function>array_udiff</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. For the comparison of the data
<parameter>data_compare_func</parameter> is used.
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. This is unlike <function>array_diff</function> which uses an
Computes the difference of arrays by using a callback function for data
comparison. This is unlike <function>array_diff</function> which uses an
internal function for comparing the data.
</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>
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>
Returns an array containing all the values of <parameter>array1</parameter>
that are not present in any of the other arguments.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>array_udiff</function> example</title>
@ -74,6 +113,9 @@ Array
</screen>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<simpara>
Please note that this function only checks one dimension of a n-dimensional
@ -81,18 +123,22 @@ Array
<literal>array_udiff($array1[0], $array2[0], "data_compare_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_assoc</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_assoc</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>

84
reference/array/functions/array-uintersect-uassoc.xml
View file

@ -1,12 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<refentry xml:id="function.array-uintersect-uassoc" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_uintersect_uassoc</refname>
<refpurpose>Computes the intersection of arrays with additional index check, compares data and indexes by a callback functions</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>array_uintersect_uassoc</methodname>
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
@ -16,12 +16,64 @@
<methodparam><type>callback</type><parameter>key_compare_func</parameter></methodparam>
</methodsynopsis>
<para>
<function>array_uintersect_uassoc</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
Computes the intersection of arrays with additional index check, compares
data and indexes by a callback functions Note that the keys are used in
the comparison unlike in <function>array_uintersect</function>.
Both the data and the indexes are compared by using separate callback functions.
</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>
<varlistentry>
<term><parameter>key_compare_func</parameter></term>
<listitem>
<para>
Key comparison callback function.
</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_uassoc</function> example</title>
@ -47,18 +99,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_assoc</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_assoc</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

78
reference/array/functions/array-uintersect.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" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_uintersect</refname>
<refpurpose>Computes the intersection of arrays, compares data by a callback function</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>array_uintersect</methodname>
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
@ -15,11 +15,55 @@
<methodparam><type>callback</type><parameter>data_compare_func</parameter></methodparam>
</methodsynopsis>
<para>
<function>array_uintersect</function> returns an array
containing all the values of <parameter>array1</parameter>
that are present in all the arguments.
The data is compared by using a callback function.
Computes the intersection of arrays, compares data by 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>
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>
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</function> example</title>
@ -46,18 +90,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_intersect</function>,
<function>array_uintersect_assoc</function>,
<function>array_intersect_uassoc</function> and
<function>array_uintersect_uassoc</function>.
<simplelist>
<member><function>array_intersect</function></member>
<member><function>array_intersect_assoc</function></member>
<member><function>array_uintersect_assoc</function></member>
<member><function>array_uintersect_uassoc</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

96
reference/array/functions/array-walk-recursive.xml
View file

@ -1,40 +1,79 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<refentry xml:id="function.array-walk-recursive" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_walk_recursive</refname>
<refpurpose>Apply a user function recursively to every member of an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>array_walk_recursive</methodname>
<methodparam><type>array</type><parameter role="reference">input</parameter></methodparam>
<methodparam><type>callback</type><parameter>funcname</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>userdata</parameter></methodparam>
</methodsynopsis>
<simpara>
<para>
Applies the user-defined function <parameter>funcname</parameter> to each
element of the <parameter>input</parameter> array. This function will recur
into deeper arrays. Typically, <parameter>funcname</parameter> takes on two
parameters. The <parameter>input</parameter> parameter's value being the first, and
the key/index second. If the optional <parameter>userdata</parameter>
parameter is supplied, it will be passed as the third parameter to
the callback <parameter>funcname</parameter>.
</simpara>
<simpara>
into deeper 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>funcname</parameter></term>
<listitem>
<para>
Typically, <parameter>funcname</parameter> takes on two parameters.
The <parameter>array</parameter> parameter's value being the first, and
the key/index second.
</para>
<note>
<para>
If <parameter>funcname</parameter> needs to be working with the
actual values of the array, specify the first parameter of
<parameter>funcname</parameter> as a
<link linkend="language.references">reference</link>. Then,
any changes made to those elements will be made in the
original array itself.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>userdata</parameter></term>
<listitem>
<para>
If the optional <parameter>userdata</parameter> parameter is supplied,
it will be passed as the third parameter to the callback
<parameter>funcname</parameter>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</simpara>
<note>
<para>
If <parameter>funcname</parameter> needs to be working with the
actual values of the array, specify the first parameter of
<parameter>funcname</parameter> as a
<link linkend="language.references">reference</link>. Then,
any changes made to those elements will be made in the
original array itself.
</para>
</note>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>array_walk_recursive</function> example</title>
@ -67,10 +106,15 @@ sour holds lemon
</para>
</example>
</para>
<simpara>
See also <function>array_walk</function>, and
&seealso.callback;.
</simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>array_walk</function></member>
<member>&seealso.callback;</member>
</simplelist>
</para>
</refsect1>
</refentry>

161
reference/array/functions/array-walk.xml
View file

@ -1,32 +1,88 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.27 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.28 $ -->
<refentry xml:id="function.array-walk" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array_walk</refname>
<refpurpose>Apply a user function to every member of an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>array_walk</methodname>
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
<methodparam><type>callback</type><parameter>funcname</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>userdata</parameter></methodparam>
</methodsynopsis>
<simpara>
&return.success;
</simpara>
<simpara>
Applies the user-defined function <parameter>funcname</parameter> to each
element of the <parameter>array</parameter> array. Typically,
<parameter>funcname</parameter> takes on two parameters.
The <parameter>array</parameter> parameter's value being the first, and
the key/index second. If the optional <parameter>userdata</parameter>
parameter is supplied, it will be passed as the third parameter to
the callback <parameter>funcname</parameter>.
element of the <parameter>array</parameter> array.
</simpara>
<simpara>
<para>
<function>array_walk</function> is not affected by the internal array
pointer of <parameter>array</parameter>. <function>array_walk</function>
will walk through the entire array regardless of pointer position.
</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>funcname</parameter></term>
<listitem>
<para>
Typically, <parameter>funcname</parameter> takes on two parameters.
The <parameter>array</parameter> parameter's value being the first, and
the key/index second.
</para>
<note>
<para>
If <parameter>funcname</parameter> needs to be working with the
actual values of the array, specify the first parameter of
<parameter>funcname</parameter> as a
<link linkend="language.references">reference</link>. Then,
any changes made to those elements will be made in the
original array itself.
</para>
</note>
<para>
Users may not change the <parameter>array</parameter> itself from the
callback function. e.g. Add/delete elements, unset elements, etc. If
the array that <function>array_walk</function> is applied to is
changed, the behavior of this function is undefined, and unpredictable.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>userdata</parameter></term>
<listitem>
<para>
If the optional <parameter>userdata</parameter> parameter is supplied,
it will be passed as the third parameter to the callback
<parameter>funcname</parameter>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
If function <parameter>funcname</parameter> requires more parameters than
given to it, an error of level <link linkend="errorfunc.constants">
E_WARNING</link> will be generated each time <function>array_walk</function>
@ -35,36 +91,34 @@
<link linkend="language.operators.errorcontrol">@</link> to the
<function>array_walk</function> call, or by using
<function>error_reporting</function>.
</simpara>
<note>
<para>
If <parameter>funcname</parameter> needs to be working with the
actual values of the array, specify the first parameter of
<parameter>funcname</parameter> as a
<link linkend="language.references">reference</link>. Then,
any changes made to those elements will be made in the
original array itself.
</para>
</note>
<note>
<para>
Passing the key and userdata to <parameter>funcname</parameter> was
added in 4.0.0
</para>
</note>
<para>
<function>array_walk</function> is not affected by the internal
array pointer of <parameter>array</parameter>. <function>
array_walk</function> will walk through the entire array
regardless of pointer position.
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
Users may not change the array itself from the callback
function. e.g. Add/delete elements, unset elements, etc. If
the array that <function>array_walk</function> is applied to
is changed, the behavior of this function is undefined, and
unpredictable.
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>4.0.0</entry>
<entry>
Passing the key and <parameter>userdata</parameter> to
<parameter>funcname</parameter> was added.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>array_walk</function> example</title>
@ -110,16 +164,21 @@ c. fruit: apple
</screen>
</example>
</para>
<simpara>
See also <function>array_walk_recursive</function>,
<function>create_function</function>,
<function>list</function>,
<link linkend="control-structures.foreach">foreach</link>,
<function>each</function>,
<function>call_user_func_array</function>, and
<function>array_map</function>, and
&seealso.callback;.
</simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>array_walk_recursive</function></member>
<member><function>create_function</function></member>
<member><function>list</function></member>
<member><function>each</function></member>
<member><function>call_user_func_array</function></member>
<member><function>array_map</function></member>
<member>&seealso.callback;</member>
<member><link linkend="control-structures.foreach">foreach</link></member>
</simplelist>
</para>
</refsect1>
</refentry>

89
reference/array/functions/array.xml
View file

@ -1,43 +1,57 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.16 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.110 -->
<!-- $Revision: 1.17 $ -->
<refentry xml:id="function.array" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>array</refname>
<refpurpose>Create an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>array</methodname>
<methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
</methodsynopsis>
<para>
Creates an array. Read the section on the
<link linkend="language.types.array">array type</link> for more information
on what an array is.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>...</parameter></term>
<listitem>
<para>
Syntax "index =&gt; values", separated by commas, define index
and values. index may be of type string or integer. When index is
omitted, an 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>
Having a trailing comma after the last defined array entry, while
unusual, is a valid syntax.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an array of the parameters. The parameters can be given
an index with the <literal>=&gt;</literal> operator. Read the section
on the <link linkend="language.types.array">array type</link> for more
information on what an array is.
</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 =&gt; values", separated by commas, define index
and values. index may be of type string or integer. When index is
omitted, an 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>
Having a trailing comma after the last defined array entry, while
unusual, is a valid syntax.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
The following example demonstrates how to create a
two-dimensional array, how to specify keys for associative
@ -133,12 +147,29 @@ echo "Hello {$foo['bar']}!"; // Hello baz!
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<para>
See also <function>array_pad</function>,
<function>list</function>,
<function>count</function>,
<link linkend="control-structures.foreach">foreach</link>, and
<function>range</function>.
<note>
<para>
<function>array</function> is a language construct used to
represent literal arrays, and not a regular function.
</para>
</note>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>array_pad</function></member>
<member><function>list</function></member>
<member><function>count</function></member>
<member><function>range</function></member>
<member><link linkend="control-structures.foreach">foreach</link></member>
<member>The <link linkend="language.types.array">array</link> type</member>
</simplelist>
</para>
</refsect1>
</refentry>

72
reference/array/functions/compact.xml
View file

@ -1,24 +1,19 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.12 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.13 $ -->
<refentry xml:id="function.compact" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>compact</refname>
<refpurpose>Create array containing variables and their values</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<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.
Creates an array containing variables and their values.
</para>
<para>
For each of these, <function>compact</function> looks for a
@ -26,21 +21,38 @@
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>
<note>
<title>Gotcha</title>
<para>
Because <link linkend="language.variables.variable">variable
variables</link> may not be used with PHP's
<link linkend="language.variables.superglobals">Superglobal
arrays</link> within functions, the Superglobal arrays may not be passed
into <function>compact</function>.
</para>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>varname</parameter></term>
<listitem>
<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>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the output array with all the variables added to it.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>compact</function> example</title>
@ -71,8 +83,26 @@ Array
</screen>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<title>Gotcha</title>
<para>
Because <link linkend="language.variables.variable">variable
variables</link> may not be used with PHP's
<link linkend="language.variables.superglobals">Superglobal
arrays</link> within functions, the Superglobal arrays may not be passed
into <function>compact</function>.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>extract</function>.
<simplelist>
<member><function>extract</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

355
reference/array/functions/extract.xml
View file

@ -1,13 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.22 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
<!-- $Revision: 1.23 $ -->
<refentry xml:id="function.extract" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>extract</refname>
<refpurpose>Import variables into the current symbol table from an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>extract</methodname>
<methodparam><type>array</type><parameter>var_array</parameter></methodparam>
@ -15,159 +14,199 @@
<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.
Import variables from an array into the current symbol table.
</para>
<note>
<para>
Beginning with version 4.0.5, this function returns the number of
variables extracted.
</para>
</note>
<note>
<para>
<constant>EXTR_IF_EXISTS</constant> and <constant>EXTR_PREFIX_IF_EXISTS</constant> were introduced in version 4.2.0.
</para>
</note>
<note>
<para>
<constant>EXTR_REFS</constant> was introduced in version 4.3.0.
</para>
</note>
<para>
<function>extract</function> checks each key to see whether it
has a valid variable name. It also checks for collisions with
existing variables in the symbol table. The way invalid/numeric
keys and collisions are treated is determined by the
<parameter>extract_type</parameter>. It can be one of the
following values:
<function>extract</function> checks each key to see whether it has a valid
variable name. It also checks for collisions with existing variables in
the symbol table.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><constant>EXTR_OVERWRITE</constant></term>
<term><parameter>var_array</parameter></term>
<listitem>
<simpara>
If there is a collision, overwrite the existing variable.
</simpara>
<para>
An associative array. This function 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>
<para>
You must use an associative array, a numerically indexed array
will not produce results unless you use <constant>EXTR_PREFIX_ALL</constant> or
<constant>EXTR_PREFIX_INVALID</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_SKIP</constant></term>
<term><parameter>extract_type</parameter></term>
<listitem>
<simpara>
If there is a collision, don't overwrite the existing
variable.
</simpara>
<para>
The way invalid/numeric keys and collisions are treated is determined
by the <parameter>extract_type</parameter>. It can be one of the
following values:
<variablelist>
<varlistentry>
<term><constant>EXTR_OVERWRITE</constant></term>
<listitem>
<simpara>
If there is a collision, overwrite the existing variable.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_SKIP</constant></term>
<listitem>
<simpara>
If there is a collision, don't overwrite the existing
variable.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_PREFIX_SAME</constant></term>
<listitem>
<simpara>If there is a collision, prefix the variable name with
<parameter>prefix</parameter>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_PREFIX_ALL</constant></term>
<listitem>
<simpara>
Prefix all variable names with
<parameter>prefix</parameter>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_PREFIX_INVALID</constant></term>
<listitem>
<simpara>
Only prefix invalid/numeric variable names with
<parameter>prefix</parameter>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_IF_EXISTS</constant></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.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_PREFIX_IF_EXISTS</constant></term>
<listitem>
<simpara>
Only create prefixed variable names if the non-prefixed version
of the same variable exists in the current symbol table.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_REFS</constant></term>
<listitem>
<simpara>
Extracts variables as references. This effectively means that the
values of the imported variables are still referencing the values of
the <parameter>var_array</parameter> parameter. You can use this flag
on its own or combine it with any other flag by OR'ing the
<parameter>extract_type</parameter>.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
If <parameter>extract_type</parameter> is not specified, it is
assumed to be <constant>EXTR_OVERWRITE</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_PREFIX_SAME</constant></term>
<term><parameter>prefix</parameter></term>
<listitem>
<simpara>If there is a collision, prefix the variable name with
<parameter>prefix</parameter>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_PREFIX_ALL</constant></term>
<listitem>
<simpara>
Prefix all variable names with
<parameter>prefix</parameter>. Beginning with PHP 4.0.5, this includes
numeric variables as well.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_PREFIX_INVALID</constant></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><constant>EXTR_IF_EXISTS</constant></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><constant>EXTR_PREFIX_IF_EXISTS</constant></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>
<varlistentry>
<term><constant>EXTR_REFS</constant></term>
<listitem>
<simpara>
Extracts variables as references. This effectively means that the
values of the imported variables are still referencing the values of
the <parameter>var_array</parameter> parameter. You can use this flag
on its own or combine it with any other flag by OR'ing the
<parameter>extract_type</parameter>. This flag was added in PHP
4.3.0.
</simpara>
<para>
Note that <parameter>prefix</parameter> is only required if
<parameter>extract_type</parameter> is <constant>EXTR_PREFIX_SAME</constant>,
<constant>EXTR_PREFIX_ALL</constant>, <constant>EXTR_PREFIX_INVALID</constant>
or <constant>EXTR_PREFIX_IF_EXISTS</constant>. If
the prefixed result is not a valid variable name, it is not
imported into the symbol table. Prefixes are automatically separated from
the array key by an underscore character.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
If <parameter>extract_type</parameter> is not specified, it is
assumed to be <constant>EXTR_OVERWRITE</constant>.
Returns the number of variables successfully imported into the symbol
table.
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
Note that <parameter>prefix</parameter> is only required if
<parameter>extract_type</parameter> is <constant>EXTR_PREFIX_SAME</constant>,
<constant>EXTR_PREFIX_ALL</constant>, <constant>EXTR_PREFIX_INVALID</constant>
or <constant>EXTR_PREFIX_IF_EXISTS</constant>. If
the prefixed result is not a valid variable name, it is not
imported into the symbol table. Prefixes are automatically separated from
the array key by an underscore character.
</para>
<para>
<function>extract</function> returns the number of variables
successfully imported into the symbol table.
</para>
<warning>
<para>
Do not use <function>extract</function> on untrusted data, like
user-input ($_GET, ...). If you do, for example, if you want to run old
code that relies on
<link linkend="security.globals">register_globals</link>
temporarily, make sure you use one of the non-overwriting
<parameter>extract_type</parameter> values such as
<constant>EXTR_SKIP</constant> and be aware that you should extract
in the same order that's defined in
<link linkend="ini.variables-order">variables_order</link> within the
<link linkend="ini">&php.ini;</link>.
</para>
</warning>
<para>
A possible use for <function>extract</function> is to import into the
symbol table variables contained in an associative array returned by
<function>wddx_deserialize</function>.
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>4.3.0</entry>
<entry>
<constant>EXTR_REFS</constant> was added.
</entry>
</row>
<row>
<entry>4.2.0</entry>
<entry>
<constant>EXTR_IF_EXISTS</constant> and <constant>EXTR_PREFIX_IF_EXISTS</constant>
were added.
</entry>
</row>
<row>
<entry>4.0.5</entry>
<entry>
This function now returns the number of variables extracted.
<constant>EXTR_PREFIX_INVALID</constant> was added.
<constant>EXTR_PREFIX_ALL</constant> includes numeric variables as well.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>extract</function> example</title>
<para>
A possible use for <function>extract</function> is to import into the
symbol table variables contained in an associative array returned by
<function>wddx_deserialize</function>.
</para>
<programlisting role="php">
<![CDATA[
<?php
@ -192,26 +231,42 @@ echo "$color, $size, $shape, $wddx_size\n";
blue, large, sphere, medium
]]>
</screen>
<para>
The <varname>$size</varname> wasn't overwritten, because we specified
<constant>EXTR_PREFIX_SAME</constant>, which resulted in
<varname>$wddx_size</varname> being created. If <constant>EXTR_SKIP</constant> was
specified, then $wddx_size wouldn't even have been created.
<constant>EXTR_OVERWRITE</constant> would have caused <varname>$size</varname> to have
value "medium", and <constant>EXTR_PREFIX_ALL</constant> would result in new variables
being named <varname>$wddx_color</varname>,
<varname>$wddx_size</varname>, and
<varname>$wddx_shape</varname>.
</para>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<warning>
<para>
Do not use <function>extract</function> on untrusted data, like user-input
($_GET, ...). If you do, for example, if you want to run old code that
relies on <link linkend="security.globals">register_globals</link>
temporarily, make sure you use one of the non-overwriting
<parameter>extract_type</parameter> values such as
<constant>EXTR_SKIP</constant> and be aware that you should extract
in the same order that's defined in
<link linkend="ini.variables-order">variables_order</link> within the
<link linkend="ini">&php.ini;</link>.
</para>
</warning>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
The <varname>$size</varname> wasn't overwritten, because we
specified <constant>EXTR_PREFIX_SAME</constant>, which resulted in
<varname>$wddx_size</varname> being created. If <constant>EXTR_SKIP</constant> was
specified, then $wddx_size wouldn't even have been created.
<constant>EXTR_OVERWRITE</constant> would have caused <varname>$size</varname> to have
value "medium", and <constant>EXTR_PREFIX_ALL</constant> 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 <constant>EXTR_PREFIX_ALL</constant> or
<constant>EXTR_PREFIX_INVALID</constant>.
</para>
<para>
See also <function>compact</function>.
<simplelist>
<member><function>compact</function></member>
</simplelist>
</para>
</refsect1>
</refentry>