cvs: phpdoc /en/reference/array/functions array-merge.xml array-multisort.xml array-push.xml array-splice.xml array-udiff-uassoc.xml array-udiff.xml
array-uintersect-uassoc.xml array-uintersect.xml array-walk-recursive.xml array-walk.xml array.xml compact.xml extract.xml
| From: | Mehdi Achour | Date: | Sun, 30 Dec 2007 23:05:06 +0000 |
| Subject: | cvs: phpdoc /en/reference/array/functions array-merge.xml array-multisort.xml array-push.xml array-splice.xml array-udiff-uassoc.xml array-udiff.xml array-uintersect-uassoc.xml array-uintersect.xml array-walk-recursive.xml array-walk.xml array.xml compact.xml extract.xml |
||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-951@lists.php.net to get a copy of this message | ||
didou Sun Dec 30 23:05:06 2007 UTC
Modified files:
/phpdoc/en/reference/array/functions array-merge.xml
array-multisort.xml
array-push.xml
array-splice.xml
array-udiff-uassoc.xml
array-udiff.xml
array-uintersect-uassoc.xml
array-uintersect.xml
array-walk-recursive.xml
array-walk.xml array.xml
compact.xml extract.xml
Log:
Switch to new doc style
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-merge.xml?r1=1.21&r2=1.22&diff_format=u Index: phpdoc/en/reference/array/functions/array-merge.xml diff -u phpdoc/en/reference/array/functions/array-merge.xml:1.21 phpdoc/en/reference/array/functions/array-merge.xml:1.22 --- phpdoc/en/reference/array/functions/array-merge.xml:1.21 Fri Aug 17 02:03:58 2007 +++ phpdoc/en/reference/array/functions/array-merge.xml Sun Dec 30 23:05:05 2007 @@ -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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-multisort.xml?r1=1.20&r2=1.21&diff_format=u Index: phpdoc/en/reference/array/functions/array-multisort.xml diff -u phpdoc/en/reference/array/functions/array-multisort.xml:1.20 phpdoc/en/reference/array/functions/array-multisort.xml:1.21 --- phpdoc/en/reference/array/functions/array-multisort.xml:1.20 Wed Nov 21 15:01:30 2007 +++ phpdoc/en/reference/array/functions/array-multisort.xml Sun Dec 30 23:05:05 2007 @@ -1,25 +1,20 @@ <?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 dimensions. @@ -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. - </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. + &return.success; </para> - + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>Sorting multiple arrays</title> @@ -112,7 +71,6 @@ </screen> </example> </para> - <para> <example> <title>Sorting multi-dimensional array</title> @@ -157,7 +115,6 @@ </screen> </example> </para> - <para> <example> <title>Sorting database results</title> @@ -238,7 +195,6 @@ </screen> </example> </para> - <para> <example> <title>Case insensitive sorting</title> @@ -278,7 +234,6 @@ </screen> </example> </para> - </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-push.xml?r1=1.15&r2=1.16&diff_format=u Index: phpdoc/en/reference/array/functions/array-push.xml diff -u phpdoc/en/reference/array/functions/array-push.xml:1.15 phpdoc/en/reference/array/functions/array-push.xml:1.16 --- phpdoc/en/reference/array/functions/array-push.xml:1.15 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/array-push.xml Sun Dec 30 23:05:05 2007 @@ -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 @@ </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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-splice.xml?r1=1.18&r2=1.19&diff_format=u Index: phpdoc/en/reference/array/functions/array-splice.xml diff -u phpdoc/en/reference/array/functions/array-splice.xml:1.18 phpdoc/en/reference/array/functions/array-splice.xml:1.19 --- phpdoc/en/reference/array/functions/array-splice.xml:1.18 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/array-splice.xml Sun Dec 30 23:05:05 2007 @@ -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. - </para> - <para> - If <parameter>length</parameter> is omitted, removes everything - from <parameter>offset</parameter> to the end of the array. If - <parameter>length</parameter> is specified and is positive, then - that many elements will be removed. If - <parameter>length</parameter> is specified and is negative then - the end of the removed portion will be that many elements from - the end of the array. Tip: to remove everything from - <parameter>offset</parameter> to the end of the array when - <parameter>replacement</parameter> is also specified, use - <literal>count($input)</literal> for - <parameter>length</parameter>. - </para> - <para> - If <parameter>replacement</parameter> array is specified, then - the removed elements are replaced with elements from this array. - If <parameter>offset</parameter> and - <parameter>length</parameter> are such that nothing is removed, - then the elements from the <parameter>replacement</parameter> - array are inserted in the place specified by the - <parameter>offset</parameter>. 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> + <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> - 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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-udiff-uassoc.xml?r1=1.13&r2=1.14&diff_format=u Index: phpdoc/en/reference/array/functions/array-udiff-uassoc.xml diff -u phpdoc/en/reference/array/functions/array-udiff-uassoc.xml:1.13 phpdoc/en/reference/array/functions/array-udiff-uassoc.xml:1.14 --- phpdoc/en/reference/array/functions/array-udiff-uassoc.xml:1.13 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/array-udiff-uassoc.xml Sun Dec 30 23:05:06 2007 @@ -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 @@ 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 @@ "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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-udiff.xml?r1=1.12&r2=1.13&diff_format=u Index: phpdoc/en/reference/array/functions/array-udiff.xml diff -u phpdoc/en/reference/array/functions/array-udiff.xml:1.12 phpdoc/en/reference/array/functions/array-udiff.xml:1.13 --- phpdoc/en/reference/array/functions/array-udiff.xml:1.12 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/array-udiff.xml Sun Dec 30 23:05:06 2007 @@ -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 @@ </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 @@ <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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-uintersect-uassoc.xml?r1=1.7&r2=1.8&diff_format=u Index: phpdoc/en/reference/array/functions/array-uintersect-uassoc.xml diff -u phpdoc/en/reference/array/functions/array-uintersect-uassoc.xml:1.7 phpdoc/en/reference/array/functions/array-uintersect-uassoc.xml:1.8 --- phpdoc/en/reference/array/functions/array-uintersect-uassoc.xml:1.7 Tue Aug 28 08:12:18 2007 +++ phpdoc/en/reference/array/functions/array-uintersect-uassoc.xml Sun Dec 30 23:05:06 2007 @@ -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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-uintersect.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc/en/reference/array/functions/array-uintersect.xml diff -u phpdoc/en/reference/array/functions/array-uintersect.xml:1.6 phpdoc/en/reference/array/functions/array-uintersect.xml:1.7 --- phpdoc/en/reference/array/functions/array-uintersect.xml:1.6 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/array-uintersect.xml Sun Dec 30 23:05:06 2007 @@ -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> + 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. - The data is compared by using a callback function. </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>array_uintersect</function> example</title> @@ -46,18 +90,16 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-walk-recursive.xml?r1=1.10&r2=1.11&diff_format=u Index: phpdoc/en/reference/array/functions/array-walk-recursive.xml diff -u phpdoc/en/reference/array/functions/array-walk-recursive.xml:1.10 phpdoc/en/reference/array/functions/array-walk-recursive.xml:1.11 --- phpdoc/en/reference/array/functions/array-walk-recursive.xml:1.10 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/array-walk-recursive.xml Sun Dec 30 23:05:06 2007 @@ -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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-walk.xml?r1=1.27&r2=1.28&diff_format=u Index: phpdoc/en/reference/array/functions/array-walk.xml diff -u phpdoc/en/reference/array/functions/array-walk.xml:1.27 phpdoc/en/reference/array/functions/array-walk.xml:1.28 --- phpdoc/en/reference/array/functions/array-walk.xml:1.27 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/array-walk.xml Sun Dec 30 23:05:06 2007 @@ -1,13 +1,12 @@ <?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> @@ -15,18 +14,75 @@ <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> - <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. </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> + 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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array.xml?r1=1.16&r2=1.17&diff_format=u Index: phpdoc/en/reference/array/functions/array.xml diff -u phpdoc/en/reference/array/functions/array.xml:1.16 phpdoc/en/reference/array/functions/array.xml:1.17 --- phpdoc/en/reference/array/functions/array.xml:1.16 Wed Aug 15 11:40:20 2007 +++ phpdoc/en/reference/array/functions/array.xml Sun Dec 30 23:05:06 2007 @@ -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> - Returns an array of the parameters. The parameters can be given - an index with the <literal>=></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> + 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> - Syntax "index => 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. + <variablelist> + <varlistentry> + <term><parameter>...</parameter></term> + <listitem> + <para> + Syntax "index => 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> - Having a trailing comma after the last defined array entry, while - unusual, is a valid syntax. + Returns an array of the parameters. The parameters can be given + an index with the <literal>=></literal> operator. 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="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 @@ </programlisting> </example> </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; + <para> + <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> - See also <function>array_pad</function>, - <function>list</function>, - <function>count</function>, - <link linkend="control-structures.foreach">foreach</link>, and - <function>range</function>. + <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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/compact.xml?r1=1.12&r2=1.13&diff_format=u Index: phpdoc/en/reference/array/functions/compact.xml diff -u phpdoc/en/reference/array/functions/compact.xml:1.12 phpdoc/en/reference/array/functions/compact.xml:1.13 --- phpdoc/en/reference/array/functions/compact.xml:1.12 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/compact.xml Sun Dec 30 23:05:06 2007 @@ -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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/extract.xml?r1=1.22&r2=1.23&diff_format=u Index: phpdoc/en/reference/array/functions/extract.xml diff -u phpdoc/en/reference/array/functions/extract.xml:1.22 phpdoc/en/reference/array/functions/extract.xml:1.23 --- phpdoc/en/reference/array/functions/extract.xml:1.22 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/extract.xml Sun Dec 30 23:05:06 2007 @@ -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> - <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> + <term><parameter>var_array</parameter></term> <listitem> - <simpara> - Prefix all variable names with - <parameter>prefix</parameter>. Beginning with PHP 4.0.5, this includes - numeric variables as well. - </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_PREFIX_INVALID</constant></term> + <term><parameter>extract_type</parameter></term> <listitem> - <simpara> - Only prefix invalid/numeric variable names with - <parameter>prefix</parameter>. This flag was added in - PHP 4.0.5. - </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_IF_EXISTS</constant></term> + <term><parameter>prefix</parameter></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>. - </para> - <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. + 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> + </refsect1> + <refsect1 role="changelog"> + &reftitle.changelog; <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 @@ 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>
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-merge.xml?r1=1.21&r2=1.22&diff_format=u Index: phpdoc/en/reference/array/functions/array-merge.xml diff -u phpdoc/en/reference/array/functions/array-merge.xml:1.21 phpdoc/en/reference/array/functions/array-merge.xml:1.22 --- phpdoc/en/reference/array/functions/array-merge.xml:1.21 Fri Aug 17 02:03:58 2007 +++ phpdoc/en/reference/array/functions/array-merge.xml Sun Dec 30 23:05:05 2007 @@ -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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-multisort.xml?r1=1.20&r2=1.21&diff_format=u Index: phpdoc/en/reference/array/functions/array-multisort.xml diff -u phpdoc/en/reference/array/functions/array-multisort.xml:1.20 phpdoc/en/reference/array/functions/array-multisort.xml:1.21 --- phpdoc/en/reference/array/functions/array-multisort.xml:1.20 Wed Nov 21 15:01:30 2007 +++ phpdoc/en/reference/array/functions/array-multisort.xml Sun Dec 30 23:05:05 2007 @@ -1,25 +1,20 @@ <?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 dimensions. @@ -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. - </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. + &return.success; </para> - + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>Sorting multiple arrays</title> @@ -112,7 +71,6 @@ </screen> </example> </para> - <para> <example> <title>Sorting multi-dimensional array</title> @@ -157,7 +115,6 @@ </screen> </example> </para> - <para> <example> <title>Sorting database results</title> @@ -238,7 +195,6 @@ </screen> </example> </para> - <para> <example> <title>Case insensitive sorting</title> @@ -278,7 +234,6 @@ </screen> </example> </para> - </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-push.xml?r1=1.15&r2=1.16&diff_format=u Index: phpdoc/en/reference/array/functions/array-push.xml diff -u phpdoc/en/reference/array/functions/array-push.xml:1.15 phpdoc/en/reference/array/functions/array-push.xml:1.16 --- phpdoc/en/reference/array/functions/array-push.xml:1.15 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/array-push.xml Sun Dec 30 23:05:05 2007 @@ -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 @@ </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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-splice.xml?r1=1.18&r2=1.19&diff_format=u Index: phpdoc/en/reference/array/functions/array-splice.xml diff -u phpdoc/en/reference/array/functions/array-splice.xml:1.18 phpdoc/en/reference/array/functions/array-splice.xml:1.19 --- phpdoc/en/reference/array/functions/array-splice.xml:1.18 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/array-splice.xml Sun Dec 30 23:05:05 2007 @@ -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. - </para> - <para> - If <parameter>length</parameter> is omitted, removes everything - from <parameter>offset</parameter> to the end of the array. If - <parameter>length</parameter> is specified and is positive, then - that many elements will be removed. If - <parameter>length</parameter> is specified and is negative then - the end of the removed portion will be that many elements from - the end of the array. Tip: to remove everything from - <parameter>offset</parameter> to the end of the array when - <parameter>replacement</parameter> is also specified, use - <literal>count($input)</literal> for - <parameter>length</parameter>. - </para> - <para> - If <parameter>replacement</parameter> array is specified, then - the removed elements are replaced with elements from this array. - If <parameter>offset</parameter> and - <parameter>length</parameter> are such that nothing is removed, - then the elements from the <parameter>replacement</parameter> - array are inserted in the place specified by the - <parameter>offset</parameter>. 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> + <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> - 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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-udiff-uassoc.xml?r1=1.13&r2=1.14&diff_format=u Index: phpdoc/en/reference/array/functions/array-udiff-uassoc.xml diff -u phpdoc/en/reference/array/functions/array-udiff-uassoc.xml:1.13 phpdoc/en/reference/array/functions/array-udiff-uassoc.xml:1.14 --- phpdoc/en/reference/array/functions/array-udiff-uassoc.xml:1.13 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/array-udiff-uassoc.xml Sun Dec 30 23:05:06 2007 @@ -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 @@ 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 @@ "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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-udiff.xml?r1=1.12&r2=1.13&diff_format=u Index: phpdoc/en/reference/array/functions/array-udiff.xml diff -u phpdoc/en/reference/array/functions/array-udiff.xml:1.12 phpdoc/en/reference/array/functions/array-udiff.xml:1.13 --- phpdoc/en/reference/array/functions/array-udiff.xml:1.12 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/array-udiff.xml Sun Dec 30 23:05:06 2007 @@ -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 @@ </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 @@ <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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-uintersect-uassoc.xml?r1=1.7&r2=1.8&diff_format=u Index: phpdoc/en/reference/array/functions/array-uintersect-uassoc.xml diff -u phpdoc/en/reference/array/functions/array-uintersect-uassoc.xml:1.7 phpdoc/en/reference/array/functions/array-uintersect-uassoc.xml:1.8 --- phpdoc/en/reference/array/functions/array-uintersect-uassoc.xml:1.7 Tue Aug 28 08:12:18 2007 +++ phpdoc/en/reference/array/functions/array-uintersect-uassoc.xml Sun Dec 30 23:05:06 2007 @@ -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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-uintersect.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc/en/reference/array/functions/array-uintersect.xml diff -u phpdoc/en/reference/array/functions/array-uintersect.xml:1.6 phpdoc/en/reference/array/functions/array-uintersect.xml:1.7 --- phpdoc/en/reference/array/functions/array-uintersect.xml:1.6 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/array-uintersect.xml Sun Dec 30 23:05:06 2007 @@ -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> + 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. - The data is compared by using a callback function. </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>array_uintersect</function> example</title> @@ -46,18 +90,16 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-walk-recursive.xml?r1=1.10&r2=1.11&diff_format=u Index: phpdoc/en/reference/array/functions/array-walk-recursive.xml diff -u phpdoc/en/reference/array/functions/array-walk-recursive.xml:1.10 phpdoc/en/reference/array/functions/array-walk-recursive.xml:1.11 --- phpdoc/en/reference/array/functions/array-walk-recursive.xml:1.10 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/array-walk-recursive.xml Sun Dec 30 23:05:06 2007 @@ -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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-walk.xml?r1=1.27&r2=1.28&diff_format=u Index: phpdoc/en/reference/array/functions/array-walk.xml diff -u phpdoc/en/reference/array/functions/array-walk.xml:1.27 phpdoc/en/reference/array/functions/array-walk.xml:1.28 --- phpdoc/en/reference/array/functions/array-walk.xml:1.27 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/array-walk.xml Sun Dec 30 23:05:06 2007 @@ -1,13 +1,12 @@ <?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> @@ -15,18 +14,75 @@ <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> - <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. </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> + 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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array.xml?r1=1.16&r2=1.17&diff_format=u Index: phpdoc/en/reference/array/functions/array.xml diff -u phpdoc/en/reference/array/functions/array.xml:1.16 phpdoc/en/reference/array/functions/array.xml:1.17 --- phpdoc/en/reference/array/functions/array.xml:1.16 Wed Aug 15 11:40:20 2007 +++ phpdoc/en/reference/array/functions/array.xml Sun Dec 30 23:05:06 2007 @@ -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> - Returns an array of the parameters. The parameters can be given - an index with the <literal>=></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> + 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> - Syntax "index => 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. + <variablelist> + <varlistentry> + <term><parameter>...</parameter></term> + <listitem> + <para> + Syntax "index => 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> - Having a trailing comma after the last defined array entry, while - unusual, is a valid syntax. + Returns an array of the parameters. The parameters can be given + an index with the <literal>=></literal> operator. 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="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 @@ </programlisting> </example> </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; + <para> + <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> - See also <function>array_pad</function>, - <function>list</function>, - <function>count</function>, - <link linkend="control-structures.foreach">foreach</link>, and - <function>range</function>. + <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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/compact.xml?r1=1.12&r2=1.13&diff_format=u Index: phpdoc/en/reference/array/functions/compact.xml diff -u phpdoc/en/reference/array/functions/compact.xml:1.12 phpdoc/en/reference/array/functions/compact.xml:1.13 --- phpdoc/en/reference/array/functions/compact.xml:1.12 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/compact.xml Sun Dec 30 23:05:06 2007 @@ -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 @@ </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/extract.xml?r1=1.22&r2=1.23&diff_format=u Index: phpdoc/en/reference/array/functions/extract.xml diff -u phpdoc/en/reference/array/functions/extract.xml:1.22 phpdoc/en/reference/array/functions/extract.xml:1.23 --- phpdoc/en/reference/array/functions/extract.xml:1.22 Wed Jun 20 22:24:15 2007 +++ phpdoc/en/reference/array/functions/extract.xml Sun Dec 30 23:05:06 2007 @@ -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> - <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> + <term><parameter>var_array</parameter></term> <listitem> - <simpara> - Prefix all variable names with - <parameter>prefix</parameter>. Beginning with PHP 4.0.5, this includes - numeric variables as well. - </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_PREFIX_INVALID</constant></term> + <term><parameter>extract_type</parameter></term> <listitem> - <simpara> - Only prefix invalid/numeric variable names with - <parameter>prefix</parameter>. This flag was added in - PHP 4.0.5. - </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_IF_EXISTS</constant></term> + <term><parameter>prefix</parameter></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>. - </para> - <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. + 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> + </refsect1> + <refsect1 role="changelog"> + &reftitle.changelog; <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 @@ 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>