From f09c05c447a1fa91cf3c690d567d74fde234bf88 Mon Sep 17 00:00:00 2001 From: Hannes Magnusson Date: Thu, 24 May 2007 08:32:49 +0000 Subject: [PATCH] Implement the "new"-doc-style git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@236226 c90b9560-bf6c-de11-be94-00142212c4b1 --- .../array/functions/array-change-key-case.xml | 101 +++++++++--- reference/array/functions/array-chunk.xml | 94 ++++++++--- reference/array/functions/array-combine.xml | 70 ++++++-- .../array/functions/array-count-values.xml | 61 ++++++- .../array/functions/array-diff-assoc.xml | 144 +++++++++++++---- reference/array/functions/array-diff-key.xml | 129 +++++++++++---- .../array/functions/array-diff-uassoc.xml | 149 +++++++++++++----- reference/array/functions/array-diff-ukey.xml | 131 +++++++++++---- reference/array/functions/array-diff.xml | 52 ++++-- reference/array/functions/array-fill-keys.xml | 92 +++++++++-- reference/array/functions/array-fill.xml | 84 ++++++++-- reference/array/functions/array-filter.xml | 102 +++++++++--- 12 files changed, 953 insertions(+), 256 deletions(-) diff --git a/reference/array/functions/array-change-key-case.xml b/reference/array/functions/array-change-key-case.xml index 9b347306fe..006aee283f 100644 --- a/reference/array/functions/array-change-key-case.xml +++ b/reference/array/functions/array-change-key-case.xml @@ -1,41 +1,83 @@ - - + array_change_key_case - Returns an array with all string keys lowercased or uppercased + Changes all keys in an array - - Description + + + &reftitle.description; arrayarray_change_key_case arrayinput intcase - array_change_key_case changes the - keys in the input array to - be all lowercase or uppercase. The change depends - on the last optional case - parameter. You can pass two constants there, - CASE_UPPER and - CASE_LOWER. The default is - CASE_LOWER. The function will leave - number indices as is. + Returns an array with all keys from input lowercased + or uppercased. Numbered indices are left as is. - - <function>array_change_key_case</function> example - + + + + &reftitle.parameters; + + + + + input + + + The array to work on + + + + + + case + + + Either CASE_UPPER or + CASE_LOWER (default) + + + + + + + + + + &reftitle.returnvalues; + + Returns an array with its keys lower or uppercased, or false if + input is not an array. + + + + + &reftitle.errors; + + Throws E_WARNING if input is + not an array. + + + + + &reftitle.examples; + + + <function>array_change_key_case</function> example + 1, "SecOnd" => 4); print_r(array_change_key_case($input_array, CASE_UPPER)); ?> ]]> - - &example.outputs; - + + &example.outputs; + 4 ) ]]> - - - - 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. + + + + + &reftitle.notes; + + + 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. + + + - + array_chunk Split an array into chunks - - Description + + + &reftitle.description; arrayarray_chunk arrayinput @@ -15,23 +15,70 @@ boolpreserve_keys - array_chunk splits the array into - several arrays with size 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 size large chunks. + The last chunk may contain less than size elements. + + + + &reftitle.parameters; - By setting the optional preserve_keys - 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;. + + + + input + + + The array to work on + + + + + + size + + + The size of each chunk + + + + + + preserve_keys + + + When set to &true; keys will be preserved. + Default is &false; which will reindex the chunk numerically + + + + + - - <function>array_chunk</function> example - + + + + &reftitle.returnvalues; + + Returns a multidimensional numerically indexed array, starting with zero, + with each dimension containing size elements. + + + + + &reftitle.errors; + + If size is less than 1 + E_WARNING will be thrown and &null; returned. + + + + + &reftitle.examples; + + + <function>array_chunk</function> example + ]]> - - &example.outputs; - + + &example.outputs; + - - + + + diff --git a/reference/array/functions/array-combine.xml b/reference/array/functions/array-combine.xml index db7f8d8b10..a6e5de396e 100644 --- a/reference/array/functions/array-combine.xml +++ b/reference/array/functions/array-combine.xml @@ -1,26 +1,71 @@ - + array_combine Creates an array by using one array for keys and another for its values - - Description + + + &reftitle.description; arrayarray_combine arraykeys arrayvalues - Returns an array by using the values from the + Creates an array by using the values from the keys array as keys and the values from the values array as the corresponding values. + + + + &reftitle.parameters; - Returns &false; if the number of elements for each array isn't equal or - if the arrays are empty. + + + + keys + + + Array of keys to be used + + + + + + values + + + Array of values to be used + + + + + + + + + &reftitle.returnvalues; + + Returns the combined array, &false; if the number of elements + for each array isn't equal or if the arrays are empty. + + + + + &reftitle.errors; + + Throws E_WARNING if keys and + values are either empty or the number of elements + does not match. + + + + + &reftitle.examples; A simple <function>array_combine</function> example @@ -48,12 +93,19 @@ Array + + + + &reftitle.seealso; - See also array_merge, - array_walk, and - array_values. + + array_merge + array_walk + array_values + + - + array_count_values Counts all the values of an array - - Description + + + &reftitle.description; arrayarray_count_values arrayinput @@ -17,6 +17,44 @@ the values of the input array as keys and their frequency in input as values. + + + + &reftitle.parameters; + + + + + input + + + The array of values to count + + + + + + + + + + &reftitle.returnvalues; + + Returns an assosiative array of values from input as + keys and their count as value. + + + + + &reftitle.errors; + + Throws E_WARNING for every element which is not + string or integer. + + + + + &reftitle.examples; <function>array_count_values</function> example @@ -41,13 +79,20 @@ Array + + + + &reftitle.seealso; - See also count, - array_unique, - array_values, and - count_chars. + + count + array_unique + array_values + count_chars + + - + array_diff_assoc Computes the difference of arrays with additional index check - - Description + + + &reftitle.description; arrayarray_diff_assoc arrayarray1 arrayarray2 - array ... + array... - array_diff_assoc returns an array - containing all the values from array1 - that are not present in any of the other arguments. - Note that the keys are used in the comparison unlike - array_diff. + Compares array1 against array2 and + returns the difference. Unlike array_diff the array + keys are used in the comparision. + + + + &reftitle.parameters; + + + + + array1 + + + The array to compare from + + + + + + array2 + + + An array to compare against + + + + + + ... + + + More arrays to compare against + + + + + + + + + + &reftitle.returnvalues; + + Returns an array containing all the values from + array1 that are not present in any of the other arrays. + + + + + + + &reftitle.examples; <function>array_diff_assoc</function> example + + In this example you see the "a" => "green" + pair is present in both arrays and thus it is not in the ouput from the + function. Unlike this, the pair 0 => "red" + is in the ouput because in the second argument "red" + has key which is 1. + - - In our example above you see the "a" => "green" - pair is present in both arrays and thus it is not in the ouput from the - function. Unlike this, the pair 0 => "red" - is in the ouput because in the second argument "red" - has key which is 1. - - - Two values from key => value pairs are - considered equal only if (string) $elem1 === (string) - $elem2 . In other words a strict check takes place so - the string representations must be the same. - - + + + <function>array_diff_assoc</function> example + + Two values from key => value pairs are + considered equal only if (string) $elem1 === (string) + $elem2 . In other words a strict check takes place so + the string representations must be the same. + + + +]]> + + &example.outputs; + + 0 + [1] => 1 + ) +]]> + + + + + + + &reftitle.notes; - 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, array_diff_assoc($array1[0], $array2[0]);. + + + + &reftitle.seealso; - See also array_diff, - array_intersect, - and array_intersect_assoc. + + array_diff + array_intersect + array_intersect_assoc + + + array_diff_key Computes the difference of arrays using keys for comparison - - Description + + + &reftitle.description; arrayarray_diff_key arrayarray1 arrayarray2 - array ... + array... - array_diff_key returns an array - containing all the values of array1 - that have keys that are not present in any of the other arguments. - Note that the associativity is preserved. This function is like - array_diff except the comparison is done on the - keys instead of the values. + Compares the keys from array1 against the keys + from array2 and returns the difference. + This function is like array_diff except the + comparison is done on the keys instead of the values. + + + + &reftitle.parameters; + + + + + array1 + + + The array to compare from + + + + + + array2 + + + An array to compare against + + + + + + ... + + + More arrays to compare against + + + + + + + + + + &reftitle.returnvalues; + + Returns an array containing all the entries from + array1 that are not present in any of the other arrays. + + + + + + + &reftitle.examples; <function>array_diff_key</function> example + + The two keys from the key => value pairs are + considered equal only if + (string) $key1 === (string) $key2 . In other words + a strict type check is executed so the string representation must be + the same. + - - The two keys from the key => value pairs are - considered equal only if - (string) $key1 === (string) $key2 . In other words - a strict type check is executed so the string representation must be - the same. - + + + + &reftitle.notes; - - 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 array_diff_key($array1[0], $array2[0]);. - + + + + + &reftitle.seealso; - See also array_diff, - array_udiff - array_diff_assoc, - array_diff_uassoc, - array_udiff_assoc, - array_udiff_uassoc, - array_diff_ukey, - array_intersect, - array_intersect_assoc, - array_intersect_uassoc, - array_intersect_key and - array_intersect_ukey. + + array_diff + array_udiff + array_diff_assoc + array_diff_uassoc + array_udiff_assoc + array_udiff_uassoc + array_diff_ukey + array_intersect + array_intersect_assoc + array_intersect_uassoc + array_intersect_key + array_intersect_ukey + + - + array_diff_uassoc Computes the difference of arrays with additional index check which is performed by a user supplied callback function - - Description + + + &reftitle.description; arrayarray_diff_uassoc arrayarray1 @@ -16,23 +16,91 @@ callbackkey_compare_func - array_diff_uassoc returns an array - containing all the values from array1 - that are not present in any of the other arguments. - Note that the keys are used in the comparison unlike - array_diff. + Compares array1 against array2 and + returns the difference. Unlike array_diff the array + keys are used in the comparision. - 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 array_diff_assoc where an - internal function for comparing the indices is used. + Unlike array_diff_assoc an user supplied callback + function is used for the indices comparision, not internal function. + + + + &reftitle.parameters; + + + + + array1 + + + The array to compare from + + + + + + array2 + + + An array to compare against + + + + + + ... + + + More arrays to compare against + + + + + + key_compare_func + + + callback 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. + + + + + + + + + + &reftitle.returnvalues; + + Returns an array containing all the entries from + array1 that are not present in any of the other arrays. + + + + + + + &reftitle.examples; <function>array_diff_uassoc</function> example + + The "a" => "green" + pair is present in both arrays and thus it is not in the ouput from the + function. Unlike this, the pair 0 => "red" + is in the ouput because in the second argument "red" + has key which is 1. + + + The equality of 2 indices is checked by the user supplied callback function. + - - In our example above you see the "a" => "green" - pair is present in both arrays and thus it is not in the ouput from the - function. Unlike this, the pair 0 => "red" - is in the ouput because in the second argument "red" - has key which is 1. - - - The equality of 2 indices is checked by the user supplied callback function. - + + + + &reftitle.notes; - - 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, array_diff_uassoc($array1[0], $array2[0], "key_compare_func");. - + + + + + &reftitle.seealso; - See also - array_diff, - array_diff_assoc, - array_udiff, - array_udiff_assoc, - array_udiff_uassoc, - array_intersect, - array_intersect_assoc, - array_uintersect, - array_uintersect_assoc and - array_uintersect_uassoc. + + array_diff + array_diff_assoc + array_udiff + array_udiff_assoc + array_udiff_uassoc + array_intersect + array_intersect_assoc + array_uintersect + array_uintersect_assoc + array_uintersect_uassoc + + + array_diff_ukey Computes the difference of arrays using a callback function on the keys for comparison - - Description + + + &reftitle.description; arrayarray_diff_ukey arrayarray1 @@ -15,19 +16,82 @@ callbackkey_compare_func - array_diff_ukey returns an array - containing all the values of array1 - that have keys that are not present in any of the other arguments. - Note that the associativity is preserved. This function is like - array_diff except the comparison is done on the - keys instead of the values. + Compares the keys from array1 against the keys + from array2 and returns the difference. + This function is like array_diff except the + comparison is done on the keys instead of the values. - 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 array_diff_key an user supplied callback + function is used for the indices comparision, not internal function. + + + + &reftitle.parameters; + + + + + array1 + + + The array to compare from + + + + + + array2 + + + An array to compare against + + + + + + ... + + + More arrays to compare against + + + + + + key_compare_func + + + callback 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. + + + + + + + + + + &reftitle.returnvalues; + + Returns an array containing all the entries from + array1 that are not present in any of the other arrays. + + + + + + + &reftitle.examples; <function>array_diff_ukey</function> example @@ -64,28 +128,39 @@ array(2) { + + + + &reftitle.notes; - - 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 array_diff_ukey($array1[0], $array2[0], 'callback_func');. - + + + + + &reftitle.seealso; - See also array_diff, - array_udiff - array_diff_assoc, - array_diff_uassoc, - array_udiff_assoc, - array_udiff_uassoc, - array_diff_key, - array_intersect, - array_intersect_assoc, - array_intersect_uassoc, - array_intersect_key and - array_intersect_ukey. + + array_diff + array_udiff + array_diff_assoc + array_diff_uassoc + array_udiff_assoc + array_udiff_uassoc + array_diff_key + array_intersect + array_intersect_assoc + array_intersect_uassoc + array_intersect_key + array_intersect_ukey + + - + array_diff Computes the difference of arrays - - Description + + + &reftitle.description; arrayarray_diff arrayarray1 @@ -15,11 +15,20 @@ array ... - array_diff returns an array - containing all the values of array1 - that are not present in any of the other arguments. - Note that keys are preserved. + Compares array1 against array2 and + returns the difference. + + + + + + &reftitle.examples; <function>array_diff</function> example @@ -48,20 +57,24 @@ Array + + + + &reftitle.seealso; - + Two elements are considered equal if and only if (string) $elem1 === (string) $elem2. In words: when the string representation is the same. - + - - 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 array_diff($array1[0], $array2[0]);. - + @@ -69,12 +82,19 @@ Array + + + + &reftitle.seealso; - See also array_diff_assoc, - array_intersect, and - array_intersect_assoc. + + array_diff_assoc + array_intersect + array_intersect_assoc + + + array_fill_keys Fill an array with values, specifying keys - - Description + + + &reftitle.description; arrayarray_fill_keys arraykeys mixedvalue - array_fill_keys fills an array with the + Fills an array with the value of the value parameter, using the values of the keys array as keys. + + + + &reftitle.parameters; + + + + + keys + + + Array of values that will be used as keys + + + + + + value + + + Either an string or an array of values + + + + + + + + + + &reftitle.returnvalues; + + Returns the filled array + + + + + + + &reftitle.examples; <function>array_fill_keys</function> example @@ -28,10 +74,8 @@ $a = array_fill_keys($keys, 'banana'); print_r($a); ?> ]]> - - - $a now is: - + + &example.outputs; + + + + &reftitle.seealso; - See also array_fill and - array_combine. + + array_fill + array_combine + + + + diff --git a/reference/array/functions/array-fill.xml b/reference/array/functions/array-fill.xml index 1031f06bfa..46669097cb 100644 --- a/reference/array/functions/array-fill.xml +++ b/reference/array/functions/array-fill.xml @@ -1,13 +1,13 @@ - - + array_fill Fill an array with values - - Description + + + &reftitle.description; arrayarray_fill intstart_index @@ -15,13 +15,66 @@ mixedvalue - array_fill fills an array with + Fills an array with num entries of the value of the value parameter, keys starting at the - start_index parameter. Note that - num must be a number greater than zero, or PHP will throw - a warning. + start_index parameter. + + + + &reftitle.parameters; + + + + + start_index + + + The first index of the returned array + + + + + + num + + + Number of elements to insert + + + + + + value + + + Values to use filling + + + + + + + + + + &reftitle.returnvalues; + + Returns the filled array + + + + + &reftitle.errors; + + Throws a E_WARNING if num is + less than one. + + + + + &reftitle.examples; <function>array_fill</function> example @@ -33,9 +86,7 @@ print_r($a); ?> ]]> - - $a now is: - + &example.outputs; + + + + &reftitle.seealso; - See also str_repeat and - range. + + str_repeat + range + + - + array_filter Filters elements of an array using a callback function - - Description + + + &reftitle.description; arrayarray_filter arrayinput callbackcallback - array_filter iterates over each value in + Iterates over each value in the input array passing them to the - callback function. If the + callback function. If the callback function returns true, the current value from input is returned into the - result array. Array keys are preserved. + result array. Array keys are preserved. + + + + &reftitle.parameters; + + + + + input + + + The array to iterate over + + + + + + callback + + + The callback function to use + + + If no callback is supplied, all entries of + input equal to &false; (see + converting to + boolean) will be removed. + + + + + + + + + + &reftitle.returnvalues; + + Returns the filtered array. + + + + + + + &reftitle.examples; <function>array_filter</function> example @@ -68,21 +119,6 @@ Array ]]> - - - Users may not change the array itself from the callback - function. e.g. Add/delete an element, unset the array that - array_filter is applied to. If the array - is changed, the behavior of this function is undefined. - - - If the callback function is not supplied, - array_filter will remove all the entries of - input that are equal to &false;. See converting to boolean - for more information. - - <function>array_filter</function> without <parameter>callback</parameter> @@ -114,11 +150,29 @@ Array + + + + &reftitle.notes; + + + If the array is changed from the callback function (e.g. element + added, deleted or unset) the behavior of this function is undefined. + + + + + + &reftitle.seealso; - See also array_map, - array_reduce, and array_walk. + + array_map + array_reduce + array_walk + +