cvs: phpdoc /en/reference/array/functions array-change-key-case.xml array-chunk.xml array-combine.xml array-count-values.xml array-diff-assoc.xml
array-diff-key.xml array-diff-uassoc.xml array-diff-ukey.xml array-diff.xml array-fill-keys.xml array-fill.xml array-filter.xml

From:	Hannes Magnusson	Date:	Thu, 24 May 2007 08:32:49 +0000
Subject:	cvs: phpdoc /en/reference/array/functions array-change-key-case.xml array-chunk.xml array-combine.xml array-count-values.xml array-diff-assoc.xml array-diff-key.xml array-diff-uassoc.xml array-diff-ukey.xml array-diff.xml array-fill-keys.xml array-fill.xml array-filter.xml
Groups:	php.doc
Request:	Send a blank email to phpdoc+get-969376415@lists.php.net to get a copy of this message

bjori Thu May 24 08:32:49 2007 UTC Modified files: /phpdoc/en/reference/array/functions array-change-key-case.xml array-chunk.xml array-combine.xml array-count-values.xml array-diff-assoc.xml array-diff-key.xml array-diff-uassoc.xml array-diff-ukey.xml array-diff.xml array-fill-keys.xml array-fill.xml array-filter.xml Log: Implement the "new"-doc-style

http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-change-key-case.xml?r1=1.12&r2=1.13&diff_format=u Index: phpdoc/en/reference/array/functions/array-change-key-case.xml diff -u phpdoc/en/reference/array/functions/array-change-key-case.xml:1.12 phpdoc/en/reference/array/functions/array-change-key-case.xml:1.13 --- phpdoc/en/reference/array/functions/array-change-key-case.xml:1.12 Tue Oct 31 11:24:01 2006 +++ phpdoc/en/reference/array/functions/array-change-key-case.xml Thu May 24 08:32:49 2007 @@ -1,41 +1,83 @@ <?xml version="1.0" encoding="iso-8859-1"?> - - + <refentry id="function.array-change-key-case"> <refnamediv> <refname>array_change_key_case</refname> - <refpurpose>Returns an array with all string keys lowercased or uppercased</refpurpose> + <refpurpose>Changes all keys in an array</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>array_change_key_case</methodname> <methodparam><type>array</type><parameter>input</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>case</parameter></methodparam> </methodsynopsis> <para> - <function>array_change_key_case</function> changes the - keys in the <parameter>input</parameter> array to - be all lowercase or uppercase. The change depends - on the last optional <parameter>case</parameter> - parameter. You can pass two constants there, - <constant>CASE_UPPER</constant> and - <constant>CASE_LOWER</constant>. The default is - <constant>CASE_LOWER</constant>. The function will leave - number indices as is. + Returns an array with all keys from <parameter>input</parameter> lowercased + or uppercased. Numbered indices are left as is. </para> - <example> - <title><function>array_change_key_case</function> example</title> - <programlisting role="php"> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + + <varlistentry> + <term><parameter>input</parameter></term> + <listitem> + <para> + The array to work on + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>case</parameter></term> + <listitem> + <para> + Either <constant>CASE_UPPER</constant> or + <constant>CASE_LOWER</constant> (default) + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns an array with its keys lower or uppercased, or false if + <parameter>input</parameter> is not an array. + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <para> + Throws <constant>E_WARNING</constant> if <parameter>input</parameter> is + not an array. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example id="function.array-change-key-case.example-1"> + <title><function>array_change_key_case</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $input_array = array("FirSt" => 1, "SecOnd" => 4); print_r(array_change_key_case($input_array, CASE_UPPER)); ?> ]]> - </programlisting> - &example.outputs; - <screen> + </programlisting> + &example.outputs; + <screen> <![CDATA[ Array ( @@ -43,14 +85,21 @@ [SECOND] => 4 ) ]]> - </screen> - </example> - <para> - If an array has indices that will be the same once run through this - function (e.g. "keY" and "kEY"), the value that is later in the array - will override other indices. + </screen> + </example> </para> </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <note> + <para> + If an array has indices that will be the same once run through this + function (e.g. "keY" and "kEY"), the value that is later in the array + will override other indices. + </para> + </note> + </refsect1> </refentry>  - + <refentry id="function.array-chunk"> <refnamediv> <refname>array_chunk</refname> <refpurpose>Split an array into chunks</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>array_chunk</methodname> <methodparam><type>array</type><parameter>input</parameter></methodparam> @@ -15,23 +15,70 @@ <methodparam choice="opt"><type>bool</type><parameter>preserve_keys</parameter></methodparam> </methodsynopsis> <para> - <function>array_chunk</function> splits the array into - several arrays with <parameter>size</parameter> values - in them. You may also have an array with less values - at the end. You get the arrays as members of a - multidimensional array indexed with numbers starting - from zero. + Chunks an array into <parameter>size</parameter> large chunks. + The last chunk may contain less than <parameter>size</parameter> elements. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + + <varlistentry> + <term><parameter>input</parameter></term> + <listitem> + <para> + The array to work on + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>size</parameter></term> + <listitem> + <para> + The size of each chunk + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>preserve_keys</parameter></term> + <listitem> + <para> + When set to &true; keys will be preserved. + Default is &false; which will reindex the chunk numerically + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - By setting the optional <parameter>preserve_keys</parameter> - parameter to &true;, you can force PHP to preserve the original - keys from the input array. If you specify &false; new number - indices will be used in each resulting array with - indices starting from zero. The default is &false;. + Returns a multidimensional numerically indexed array, starting with zero, + with each dimension containing <parameter>size</parameter> elements. </para> - <example> - <title><function>array_chunk</function> example</title> - <programlisting role="php"> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <para> + If <parameter>size</parameter> is less than 1 + <constant>E_WARNING</constant> will be thrown and &null; returned. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>array_chunk</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $input_array = array('a', 'b', 'c', 'd', 'e'); @@ -39,9 +86,9 @@ print_r(array_chunk($input_array, 2, true)); ?> ]]> - </programlisting> - &example.outputs; - <screen> + </programlisting> + &example.outputs; + <screen> <![CDATA[ Array ( @@ -84,8 +131,9 @@ ) ]]> - </screen> - </example> + </screen> + </example> + </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-combine.xml?r1=1.7&r2=1.8&diff_format=u Index: phpdoc/en/reference/array/functions/array-combine.xml diff -u phpdoc/en/reference/array/functions/array-combine.xml:1.7 phpdoc/en/reference/array/functions/array-combine.xml:1.8 --- phpdoc/en/reference/array/functions/array-combine.xml:1.7 Tue Oct 31 11:24:01 2006 +++ phpdoc/en/reference/array/functions/array-combine.xml Thu May 24 08:32:49 2007 @@ -1,26 +1,71 @@ <?xml version="1.0" encoding="iso-8859-1"?> - + <refentry id="function.array-combine"> <refnamediv> <refname>array_combine</refname> <refpurpose>Creates an array by using one array for keys and another for its values</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>array_combine</methodname> <methodparam><type>array</type><parameter>keys</parameter></methodparam> <methodparam><type>array</type><parameter>values</parameter></methodparam> </methodsynopsis> <para> - Returns an <type>array</type> by using the values from the + Creates an <type>array</type> by using the values from the <parameter>keys</parameter> array as keys and the values from the <parameter>values</parameter> array as the corresponding values. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + + <varlistentry> + <term><parameter>keys</parameter></term> + <listitem> + <para> + Array of keys to be used + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>values</parameter></term> + <listitem> + <para> + Array of values to be used + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - Returns &false; if the number of elements for each array isn't equal or - if the arrays are empty. + Returns the combined <type>array</type>, &false; if the number of elements + for each array isn't equal or if the arrays are empty. </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <para> + Throws <constant>E_WARNING</constant> if <parameter>keys</parameter> and + <parameter>values</parameter> are either empty or the number of elements + does not match. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>A simple <function>array_combine</function> example</title> @@ -48,12 +93,19 @@ </screen> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>array_merge</function>, - <function>array_walk</function>, and - <function>array_values</function>. + <simplelist> + <member><function>array_merge</function></member> + <member><function>array_walk</function></member> + <member><function>array_values</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.array-count-values"> <refnamediv> <refname>array_count_values</refname> <refpurpose>Counts all the values of an array</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>array_count_values</methodname> <methodparam><type>array</type><parameter>input</parameter></methodparam> @@ -17,6 +17,44 @@ the values of the <parameter>input</parameter> array as keys and their frequency in <parameter>input</parameter> as values. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + + <varlistentry> + <term><parameter>input</parameter></term> + <listitem> + <para> + The array of values to count + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns an assosiative array of values from <parameter>input</parameter> as + keys and their count as value. + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <para> + Throws <constant>E_WARNING</constant> for every element which is not + <type>string</type> or <type>integer</type>. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>array_count_values</function> example</title> @@ -41,13 +79,20 @@ </screen> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>count</function>, - <function>array_unique</function>, - <function>array_values</function>, and - <function>count_chars</function>. + <simplelist> + <member><function>count</function></member> + <member><function>array_unique</function></member> + <member><function>array_values</function></member> + <member><function>count_chars</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.array-diff-assoc"> <refnamediv> <refname>array_diff_assoc</refname> <refpurpose>Computes the difference of arrays with additional index check</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>array_diff_assoc</methodname> <methodparam><type>array</type><parameter>array1</parameter></methodparam> <methodparam><type>array</type><parameter>array2</parameter></methodparam> - <methodparam choice="opt"><type>array</type><parameter> ...</parameter></methodparam> + <methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam> </methodsynopsis> <para> - <function>array_diff_assoc</function> returns an <type>array</type> - containing all the values from <parameter>array1</parameter> - that are not present in any of the other arguments. - Note that the keys are used in the comparison unlike - <function>array_diff</function>. + Compares <parameter>array1</parameter> against <parameter>array2</parameter> and + returns the difference. Unlike <function>array_diff</function> the array + keys are used in the comparision. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + + <varlistentry> + <term><parameter>array1</parameter></term> + <listitem> + <para> + The array to compare from + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>array2</parameter></term> + <listitem> + <para> + An array to compare against + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>...</parameter></term> + <listitem> + <para> + More arrays to compare against + </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 arrays. + </para> + </refsect1> + + + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>array_diff_assoc</function> example</title> + <para> + In this example you see the <literal>"a" => "green"</literal> + pair is present in both arrays and thus it is not in the ouput from the + function. Unlike this, the pair <literal>0 => "red"</literal> + is in the ouput because in the second argument <literal>"red"</literal> + has key which is <literal>1</literal>. + </para> <programlisting role="php"> <![CDATA[ <?php @@ -47,33 +107,61 @@ </screen> </example> </para> - <simpara> - In our example above you see the <literal>"a" => "green"</literal> - pair is present in both arrays and thus it is not in the ouput from the - function. Unlike this, the pair <literal>0 => "red"</literal> - is in the ouput because in the second argument <literal>"red"</literal> - has key which is <literal>1</literal>. - </simpara> - <simpara> - Two values from <emphasis>key => value</emphasis> pairs are - considered equal only if <literal>(string) $elem1 === (string) - $elem2 </literal>. In other words a strict check takes place so - the string representations must be the same. -  - </simpara> + <para> + <example> + <title><function>array_diff_assoc</function> example</title> + <para> + Two values from <emphasis>key => value</emphasis> pairs are + considered equal only if <literal>(string) $elem1 === (string) + $elem2 </literal>. In other words a strict check takes place so + the string representations must be the same. + </para> + <programlisting role="php"> +<![CDATA[ +<?php +$array1 = array(0, 1, 2); +$array2 = array("00", "01", "2"); +$result = array_diff_assoc($array1, $array2); +print_r($result); +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +Array +( + [0] => 0 + [1] => 1 + ) +]]> + </screen> + </example> + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> <simpara> - Please note that this function only checks one dimension of a n-dimensional + This function only checks one dimension of a n-dimensional array. Of course you can check deeper dimensions by using, for example, <literal>array_diff_assoc($array1[0], $array2[0]);</literal>. </simpara> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>array_diff</function>, - <function>array_intersect</function>, - and <function>array_intersect_assoc</function>. + <simplelist> + <member><function>array_diff</function></member> + <member><function>array_intersect</function></member> + <member><function>array_intersect_assoc</function></member> + </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.array-diff-key"> <refnamediv> <refname>array_diff_key</refname> <refpurpose>Computes the difference of arrays using keys for comparison</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>array_diff_key</methodname> <methodparam><type>array</type><parameter>array1</parameter></methodparam> <methodparam><type>array</type><parameter>array2</parameter></methodparam> - <methodparam choice="opt"><type>array</type><parameter> ...</parameter></methodparam> + <methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam> </methodsynopsis> <para> - <function>array_diff_key</function> returns an array - containing all the values of <parameter>array1</parameter> - that have keys that are not present in any of the other arguments. - Note that the associativity is preserved. This function is like - <function>array_diff</function> except the comparison is done on the - keys instead of the values. + Compares the keys from <parameter>array1</parameter> against the keys + from <parameter>array2</parameter> and returns the difference. + This function is like <function>array_diff</function> except the + comparison is done on the keys instead of the values. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + + <varlistentry> + <term><parameter>array1</parameter></term> + <listitem> + <para> + The array to compare from + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>array2</parameter></term> + <listitem> + <para> + An array to compare against + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>...</parameter></term> + <listitem> + <para> + More arrays to compare against + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns an <type>array</type> containing all the entries from + <parameter>array1</parameter> that are not present in any of the other arrays. + </para> + </refsect1> + + + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>array_diff_key</function> example</title> + <para> + The two keys from the <literal>key => value</literal> pairs are + considered equal only if + <literal>(string) $key1 === (string) $key2 </literal>. In other words + a strict type check is executed so the string representation must be + the same. + </para> <programlisting role="php"> <![CDATA[ <?php @@ -47,35 +108,39 @@ </screen> </example> </para> - <simpara> - The two keys from the <literal>key => value</literal> pairs are - considered equal only if - <literal>(string) $key1 === (string) $key2 </literal>. In other words - a strict type check is executed so the string representation must be - the same. - </simpara> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> - <simpara> - Please note that this function only checks one dimension of a n-dimensional + <para> + This function only checks one dimension of a n-dimensional array. Of course you can check deeper dimensions by using <literal>array_diff_key($array1[0], $array2[0]);</literal>. - </simpara> + </para> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>array_diff</function>, - <function>array_udiff</function> - <function>array_diff_assoc</function>, - <function>array_diff_uassoc</function>, - <function>array_udiff_assoc</function>, - <function>array_udiff_uassoc</function>, - <function>array_diff_ukey</function>, - <function>array_intersect</function>, - <function>array_intersect_assoc</function>, - <function>array_intersect_uassoc</function>, - <function>array_intersect_key</function> and - <function>array_intersect_ukey</function>. + <simplelist> + <member><function>array_diff</function></member> + <member><function>array_udiff</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_diff_ukey</function></member> + <member><function>array_intersect</function></member> + <member><function>array_intersect_assoc</function></member> + <member><function>array_intersect_uassoc</function></member> + <member><function>array_intersect_key</function></member> + <member><function>array_intersect_ukey</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.array-diff-uassoc"> <refnamediv> <refname>array_diff_uassoc</refname> <refpurpose>Computes the difference of arrays with additional index check which is performed by a user supplied callback function</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>array_diff_uassoc</methodname> <methodparam><type>array</type><parameter>array1</parameter></methodparam> @@ -16,23 +16,91 @@ <methodparam><type>callback</type><parameter>key_compare_func</parameter></methodparam> </methodsynopsis> <para> - <function>array_diff_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. - Note that the keys are used in the comparison unlike - <function>array_diff</function>. + Compares <parameter>array1</parameter> against <parameter>array2</parameter> and + returns the difference. Unlike <function>array_diff</function> the array + keys are used in the comparision. </para> <para> - This comparison is done by a 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. This is unlike <function>array_diff_assoc</function> where an - internal function for comparing the indices is used. + Unlike <function>array_diff_assoc</function> an user supplied callback + function is used for the indices comparision, not internal function. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + + <varlistentry> + <term><parameter>array1</parameter></term> + <listitem> + <para> + The array to compare from + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>array2</parameter></term> + <listitem> + <para> + An array to compare against + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>...</parameter></term> + <listitem> + <para> + More arrays to compare against + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>key_compare_func</parameter></term> + <listitem> + <para> + <type>callback</type> function to use. + The callback function must return an integer less than, equal + to, or greater than zero if the first argument is considered to + be respectively less than, equal to, or greater than the second. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns an <type>array</type> containing all the entries from + <parameter>array1</parameter> that are not present in any of the other arrays. + </para> + </refsect1> + + + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>array_diff_uassoc</function> example</title> + <para> + The <literal>"a" => "green"</literal> + pair is present in both arrays and thus it is not in the ouput from the + function. Unlike this, the pair <literal>0 => "red"</literal> + is in the ouput because in the second argument <literal>"red"</literal> + has key which is <literal>1</literal>. + </para> <programlisting role="php"> <![CDATA[ <?php @@ -62,39 +130,42 @@ ) ]]> </screen> + <simpara> + The equality of 2 indices is checked by the user supplied callback function. + </simpara> </example> </para> - <simpara> - In our example above you see the <literal>"a" => "green"</literal> - pair is present in both arrays and thus it is not in the ouput from the - function. Unlike this, the pair <literal>0 => "red"</literal> - is in the ouput because in the second argument <literal>"red"</literal> - has key which is <literal>1</literal>. - </simpara> - <simpara> - The equality of 2 indices is checked by the user supplied callback function. - </simpara> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> - <simpara> - Please note that this function only checks one dimension of a n-dimensional + <para> + This function only checks one dimension of a n-dimensional array. Of course you can check deeper dimensions by using, for example, <literal>array_diff_uassoc($array1[0], $array2[0], "key_compare_func");</literal>. - </simpara> + </para> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>array_diff</function>, - <function>array_diff_assoc</function>, - <function>array_udiff</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_udiff</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>  + <refentry id="function.array-diff-ukey"> <refnamediv> <refname>array_diff_ukey</refname> <refpurpose>Computes the difference of arrays using a callback function on the keys for comparison</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>array_diff_ukey</methodname> <methodparam><type>array</type><parameter>array1</parameter></methodparam> @@ -15,19 +16,82 @@ <methodparam><type>callback</type><parameter>key_compare_func</parameter></methodparam> </methodsynopsis> <para> - <function>array_diff_ukey</function> returns an array - containing all the values of <parameter>array1</parameter> - that have keys that are not present in any of the other arguments. - Note that the associativity is preserved. This function is like - <function>array_diff</function> except the comparison is done on the - keys instead of the values. + Compares the keys from <parameter>array1</parameter> against the keys + from <parameter>array2</parameter> and returns the difference. + This function is like <function>array_diff</function> except the + comparison is done on the keys instead of the values. </para> <para> - This comparison is done by a user supplied callback function. - It must return an integer less than, equal to, or greater than zero if the - first key is considered to be respectively less than, equal to, or - greater than the second. + Unlike <function>array_diff_key</function> an user supplied callback + function is used for the indices comparision, not internal function. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + + <varlistentry> + <term><parameter>array1</parameter></term> + <listitem> + <para> + The array to compare from + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>array2</parameter></term> + <listitem> + <para> + An array to compare against + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>...</parameter></term> + <listitem> + <para> + More arrays to compare against + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>key_compare_func</parameter></term> + <listitem> + <para> + <type>callback</type> function to use. + The callback function must return an integer less than, equal + to, or greater than zero if the first argument is considered to + be respectively less than, equal to, or greater than the second. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns an <type>array</type> containing all the entries from + <parameter>array1</parameter> that are not present in any of the other arrays. + </para> + </refsect1> + + + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>array_diff_ukey</function> example</title> @@ -64,28 +128,39 @@ </screen> </example> </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> - <simpara> - Please note that this function only checks one dimension of a n-dimensional + <para> + This function only checks one dimension of a n-dimensional array. Of course you can check deeper dimensions by using <literal>array_diff_ukey($array1[0], $array2[0], 'callback_func');</literal>. - </simpara> + </para> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>array_diff</function>, - <function>array_udiff</function> - <function>array_diff_assoc</function>, - <function>array_diff_uassoc</function>, - <function>array_udiff_assoc</function>, - <function>array_udiff_uassoc</function>, - <function>array_diff_key</function>, - <function>array_intersect</function>, - <function>array_intersect_assoc</function>, - <function>array_intersect_uassoc</function>, - <function>array_intersect_key</function> and - <function>array_intersect_ukey</function>. + <simplelist> + <member><function>array_diff</function></member> + <member><function>array_udiff</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_diff_key</function></member> + <member><function>array_intersect</function></member> + <member><function>array_intersect_assoc</function></member> + <member><function>array_intersect_uassoc</function></member> + <member><function>array_intersect_key</function></member> + <member><function>array_intersect_ukey</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.array-diff"> <refnamediv> <refname>array_diff</refname> <refpurpose>Computes the difference of arrays</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>array_diff</methodname> <methodparam><type>array</type><parameter>array1</parameter></methodparam> @@ -15,11 +15,20 @@ <methodparam choice="opt"><type>array</type><parameter> ...</parameter></methodparam> </methodsynopsis> <para> - <function>array_diff</function> returns an array - containing all the values of <parameter>array1</parameter> - that are not present in any of the other arguments. - Note that keys are preserved. + Compares <parameter>array1</parameter> against <parameter>array2</parameter> and + returns the difference. </para> + </refsect1> + +  + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>array_diff</function> example</title> @@ -48,20 +57,24 @@ </screen> </example> </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.seealso; <note> - <simpara> + <para> Two elements are considered equal if and only if <literal>(string) $elem1 === (string) $elem2</literal>. In words: when the string representation is the same.  - </simpara> + </para> </note> <note> - <simpara> - Please note that this function only checks one dimension of a n-dimensional + <para> + This function only checks one dimension of a n-dimensional array. Of course you can check deeper dimensions by using <literal>array_diff($array1[0], $array2[0]);</literal>. - </simpara> + </para> </note> <warning> <simpara> @@ -69,12 +82,19 @@  </simpara> </warning> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>array_diff_assoc</function>, - <function>array_intersect</function>, and - <function>array_intersect_assoc</function>. + <simplelist> + <member><function>array_diff_assoc</function></member> + <member><function>array_intersect</function></member> + <member><function>array_intersect_assoc</function></member> + </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.array-fill-keys"> <refnamediv> <refname>array_fill_keys</refname> <refpurpose>Fill an array with values, specifying keys</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>array_fill_keys</methodname> <methodparam><type>array</type><parameter>keys</parameter></methodparam> <methodparam><type>mixed</type><parameter>value</parameter></methodparam> </methodsynopsis> <para> - <function>array_fill_keys</function> fills an array with the + Fills an array with the value of the <parameter>value</parameter> parameter, using the values of the <parameter>keys</parameter> array as keys. </para> + </refsect1> + + <refsect1 role="parameter"> + &reftitle.parameters; + <para> + <variablelist> + + <varlistentry> + <term><parameter>keys</parameter></term> + <listitem> + <para> + Array of values that will be used as keys + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>value</parameter></term> + <listitem> + <para> + Either an string or an array of values + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the filled array + </para> + </refsect1> + + + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>array_fill_keys</function> example</title> @@ -28,10 +74,8 @@ print_r($a); ?> ]]> - </programlisting> - <para> - <varname>$a</varname> now is: - </para> + </programlisting> + &example.outputs; <screen> <![CDATA[ Array @@ -45,9 +89,37 @@ </screen> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>array_fill</function> and - <function>array_combine</function>. + <simplelist> + <member><function>array_fill</function></member> + <member><function>array_combine</function></member> + </simplelist> </para> </refsect1> + </refentry> + + http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/array/functions/array-fill.xml?r1=1.10&r2=1.11&diff_format=u Index: phpdoc/en/reference/array/functions/array-fill.xml diff -u phpdoc/en/reference/array/functions/array-fill.xml:1.10 phpdoc/en/reference/array/functions/array-fill.xml:1.11 --- phpdoc/en/reference/array/functions/array-fill.xml:1.10 Tue Oct 31 11:24:01 2006 +++ phpdoc/en/reference/array/functions/array-fill.xml Thu May 24 08:32:49 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> - - + <refentry id="function.array-fill"> <refnamediv> <refname>array_fill</refname> <refpurpose>Fill an array with values</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>array_fill</methodname> <methodparam><type>int</type><parameter>start_index</parameter></methodparam> @@ -15,13 +15,66 @@ <methodparam><type>mixed</type><parameter>value</parameter></methodparam> </methodsynopsis> <para> - <function>array_fill</function> fills an array with + Fills an array with <parameter>num</parameter> entries of the value of the <parameter>value</parameter> parameter, keys starting at the - <parameter>start_index</parameter> parameter. Note that <parameter> - num</parameter> must be a number greater than zero, or PHP will throw - a warning. + <parameter>start_index</parameter> parameter. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + + <varlistentry> + <term><parameter>start_index</parameter></term> + <listitem> + <para> + The first index of the returned array + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>num</parameter></term> + <listitem> + <para> + Number of elements to insert + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>value</parameter></term> + <listitem> + <para> + Values to use filling + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the filled array + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <para> + Throws a <constant>E_WARNING</constant> if <parameter>num</parameter> is + less than one. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>array_fill</function> example</title> @@ -33,9 +86,7 @@ ?> ]]> </programlisting> - <para> - <varname>$a</varname> now is: - </para> + &example.outputs; <screen> <![CDATA[ Array @@ -51,11 +102,18 @@ </screen> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>str_repeat</function> and - <function>range</function>. + <simplelist> + <member><function>str_repeat</function></member> + <member><function>range</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.array-filter"> <refnamediv> <refname>array_filter</refname> <refpurpose>Filters elements of an array using a callback function</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>array_filter</methodname> <methodparam><type>array</type><parameter>input</parameter></methodparam> <methodparam choice="opt"><type>callback</type><parameter>callback</parameter></methodparam> </methodsynopsis> <para> - <function>array_filter</function> iterates over each value in + Iterates over each value in the <parameter>input</parameter> array passing them to the - <parameter>callback</parameter> function. If the <parameter> + <parameter>callback</parameter> function. If the <parameter> callback</parameter> function returns true, the current value from <parameter>input</parameter> is returned into the - result array. Array keys are preserved. + result array. Array keys are preserved. </para> +</refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + + <varlistentry> + <term><parameter>input</parameter></term> + <listitem> + <para> + The array to iterate over + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>callback</parameter></term> + <listitem> + <para> + The callback function to use + </para> + <para> + If no <parameter>callback</parameter> is supplied, all entries of + <parameter>input</parameter> equal to &false; (see + <link linkend="language.types.boolean.casting">converting to + boolean</link>) will be removed. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the filtered array. + </para> + </refsect1> + + + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>array_filter</function> example</title> @@ -68,21 +119,6 @@ ]]> </screen> </example> - </para> - <para> - Users may not change the array itself from the callback - function. e.g. Add/delete an element, unset the array that - <function>array_filter</function> is applied to. If the array - is changed, the behavior of this function is undefined. - </para> - <para> - If the <parameter>callback</parameter> function is not supplied, - <function>array_filter</function> will remove all the entries of - <parameter>input</parameter> that are equal to &false;. See <link - linkend="language.types.boolean.casting">converting to boolean</link> - for more information. - </para> - <para> <example> <title><function>array_filter</function> without <parameter>callback</parameter></title> @@ -114,11 +150,29 @@ </screen> </example> </para> - <para> - See also <function>array_map</function>, - <function>array_reduce</function>, and <function>array_walk</function>. + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <caution> + <para> + If the array is changed from the callback function (e.g. element + added, deleted or unset) the behavior of this function is undefined. + </para> + </caution> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>array_map</function></member> + <member><function>array_reduce</function></member> + <member><function>array_walk</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file

cvs: phpdoc /en/reference/array/functions array-change-key-case.xml array-chunk.xml array-combine.xml array-count-values.xml array-diff-assoc.xml array-diff-key.xml array-diff-uassoc.xml array-diff-ukey.xml array-diff.xml array-fill-keys.xml array-fill.xml array-filter.xml

cvs: phpdoc /en/reference/array/functions array-change-key-case.xml array-chunk.xml array-combine.xml array-count-values.xml array-diff-assoc.xml
array-diff-key.xml array-diff-uassoc.xml array-diff-ukey.xml array-diff.xml array-fill-keys.xml array-fill.xml array-filter.xml