diff --git a/reference/array/functions/array-merge.xml b/reference/array/functions/array-merge.xml index 35aa8a7d3e..107dd353c0 100644 --- a/reference/array/functions/array-merge.xml +++ b/reference/array/functions/array-merge.xml @@ -1,13 +1,12 @@ - - + array_merge Merge one or more arrays - - Description + + &reftitle.description; arrayarray_merge arrayarray1 @@ -15,9 +14,9 @@ array... - array_merge 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. 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. + + + &reftitle.parameters; + + + + array1 + + + Initial array to merge. + + + + + array + + + Variable list of arrays to recursively merge. + + + + + + + + &reftitle.returnvalues; + + Returns the resulting array. + + + + &reftitle.examples; <function>array_merge</function> example @@ -142,10 +173,15 @@ Array + + + &reftitle.seealso; - See also array_merge_recursive, - array_combine and - array operators. + + array_merge_recursive + array_combine + array operators + diff --git a/reference/array/functions/array-multisort.xml b/reference/array/functions/array-multisort.xml index 61326c9a03..1e491118d3 100644 --- a/reference/array/functions/array-multisort.xml +++ b/reference/array/functions/array-multisort.xml @@ -1,24 +1,19 @@ - - + array_multisort Sort multiple or multi-dimensional arrays - - Description + + &reftitle.description; boolarray_multisort arrayar1 mixedarg mixed... array... - - - &return.success; - array_multisort can be used to sort several arrays at once, or a multi-dimensional array by one or more @@ -28,51 +23,15 @@ Associative (string) keys will be maintained, but numeric keys will be re-indexed. + + + &reftitle.returnvalues; - The input arrays are treated as columns of a table to be sorted - by rows - this resembles the functionality of SQL ORDER BY - clause. The first array is the primary one to sort by. The rows - (values) in that array that compare the same are sorted by the - next input array, and so on. + &return.success; - - 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. - - - Sorting order flags: - - - SORT_ASC - Sort in ascending order - - - SORT_DESC - Sort in descending order - - - - - Sorting type flags: - - - SORT_REGULAR - Compare items normally - - - SORT_NUMERIC - Compare items numerically - - - SORT_STRING - Compare items as strings - - - - - 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 SORT_ASC and - SORT_REGULAR before each new array argument. - - + + + &reftitle.examples; Sorting multiple arrays @@ -112,7 +71,6 @@ array(4) { - Sorting multi-dimensional array @@ -157,7 +115,6 @@ array(2) { - Sorting database results @@ -238,7 +195,6 @@ volume | edition - Case insensitive sorting @@ -278,7 +234,6 @@ Array - diff --git a/reference/array/functions/array-push.xml b/reference/array/functions/array-push.xml index f1d49a24eb..93b3b6f471 100644 --- a/reference/array/functions/array-push.xml +++ b/reference/array/functions/array-push.xml @@ -1,13 +1,12 @@ - - + array_push Push one or more elements onto the end of array - - Description + + &reftitle.description; intarray_push arrayarray @@ -15,11 +14,10 @@ mixed... - array_push treats - array as a stack, and pushes the passed - variables onto the end of array. The - length of array increases by the number of - variables pushed. Has the same effect as: + array_push treats array as a + stack, and pushes the passed variables onto the end of + array. The length of array + increases by the number of variables pushed. Has the same effect as: repeated for each var. + + + If you use array_push to add one element to the + array it's better to use $array[] = because in that + way there is no overhead of calling a function. + + + + + array_push will raise a warning if the first + argument is not an array. This differs from the + $var[] behaviour where a new array is created. + + + + + &reftitle.parameters; + + + + array + + + The input array. + + + + + var + + + The pushed value. + + + + + + + + &reftitle.returnvalues; Returns the new number of elements in the array. + + + &reftitle.examples; <function>array_push</function> example @@ -58,24 +99,15 @@ Array - - - If you use array_push to add one element to the - array it's better to use $array[] = because in that - way there is no overhead of calling a function. - - - - - array_push will raise a warning if the first - argument is not an array. This differs from the - $var[] behaviour where a new array is created. - - + + + &reftitle.seealso; - See also array_pop, - array_shift, and - array_unshift. + + array_pop + array_shift + array_unshift + diff --git a/reference/array/functions/array-splice.xml b/reference/array/functions/array-splice.xml index 5dbe89cc48..3c29a8042e 100644 --- a/reference/array/functions/array-splice.xml +++ b/reference/array/functions/array-splice.xml @@ -1,13 +1,12 @@ - - + array_splice Remove a portion of the array and replace it with something else - - Description + + &reftitle.description; arrayarray_splice arrayinput @@ -16,101 +15,89 @@ arrayreplacement - array_splice removes the elements designated - by offset and - length from the - input array, and replaces them with the - elements of the replacement array, if - supplied. It returns an array containing the extracted elements. + Removes the elements designated by offset and + length from the input array, + and replaces them with the elements of the + replacement array, if supplied. + + Note that numeric keys in input are not preserved. + + + &reftitle.parameters; - If offset is positive then the start of - removed portion is at that offset from the beginning of the - input array. If - offset is negative then it starts that far - from the end of the input array. + + + input + + + The input array. + + + + + offset + + + If offset is positive then the start of removed + portion is at that offset from the beginning of the + input array. If offset + is negative then it starts that far from the end of the + input array. + + + + + length + + + If length is omitted, removes everything + from offset to the end of the array. If + length is specified and is positive, then + that many elements will be removed. If + length 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 + offset to the end of the array when + replacement is also specified, use + count($input) for + length. + + + + + replacement + + + If replacement array is specified, then the + removed elements are replaced with elements from this array. + + + If offset and length + are such that nothing is removed, then the elements from the + replacement array are inserted in the place + specified by the offset. Note that keys in + replacement array are not preserved. + + + If replacement is just one element it is + not necessary to put array() + around it, unless the element is an array itself. + + + + + + + &reftitle.returnvalues; - If length is omitted, removes everything - from offset to the end of the array. If - length is specified and is positive, then - that many elements will be removed. If - length 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 - offset to the end of the array when - replacement is also specified, use - count($input) for - length. - - - If replacement array is specified, then - the removed elements are replaced with elements from this array. - If offset and - length are such that nothing is removed, - then the elements from the replacement - array are inserted in the place specified by the - offset. Note that keys in replacement - array are not preserved. - If replacement is just one element it is - not necessary to put array() - around it, unless the element is an array itself. - - - The following statements change the values of $input - the same way: - - <function>array_splice</function> equivalents - - - - - 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) - - - - -
- - - Returns the array consisting of removed elements. + Returns the array consisting of the extracted elements. + + + &reftitle.examples; <function>array_splice</function> examples @@ -144,9 +131,39 @@ array_splice($input, 3, 0, "purple"); - See also array_slice, - unset, and - array_merge. + + <function>array_splice</function> examples + + The following statements change the values of $input + the same way: + + + +]]> + + + + + + &reftitle.seealso; + + + array_slice + unset + array_merge + diff --git a/reference/array/functions/array-udiff-uassoc.xml b/reference/array/functions/array-udiff-uassoc.xml index 1ea8302311..a792ba3e2f 100644 --- a/reference/array/functions/array-udiff-uassoc.xml +++ b/reference/array/functions/array-udiff-uassoc.xml @@ -1,13 +1,12 @@ - - + array_udiff_uassoc Computes the difference of arrays with additional index check, compares data and indexes by a callback function - - Description + + &reftitle.description; arrayarray_udiff_uassoc arrayarray1 @@ -17,20 +16,79 @@ callbackkey_compare_func - array_udiff_uassoc returns an array - containing all the values from array1 - 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. + + Note that the keys are used in the comparison unlike array_diff and array_udiff. - The comparison of arrays' data is performed by using an user-supplied - callback : data_compare_func. In this aspect - the behaviour is opposite to the behaviour of - array_diff_assoc which uses internal function for - comparison. The comparison of keys (indices) is done also by the - callback function key_compare_func. This - behaviour is unlike what array_udiff_assoc does, since - the latter compares the indices by using an internal function. + + + &reftitle.parameters; + + + + array1 + + + The first array. + + + + + array2 + + + The second array. + + + + + data_compare_func + + + The callback comparison function. + + + 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. + + + The comparison of arrays' data is performed by using an user-supplied + callback : data_compare_func. In this aspect + the behaviour is opposite to the behaviour of + array_diff_assoc which uses internal function for + comparison. + + + + + key_compare_func + + + The comparison of keys (indices) is done also by the callback function + key_compare_func. This behaviour is unlike what + array_udiff_assoc does, since the latter compares + the indices by using an internal function. + + + + + + + + &reftitle.returnvalues; + + Returns an array containing all the values from + array1 that are not present in any of the other + arguments. + + + + &reftitle.examples; <function>array_udiff_uassoc</function> example @@ -93,13 +151,9 @@ Array pair is present in both arrays and thus it is not in the ouput from the function. Keep in mind that you have to supply 2 callback functions. - - 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. - + + + &reftitle.notes; Please note that this function only checks one dimension of a n-dimensional @@ -108,18 +162,21 @@ Array "key_compare_func");. + + + &reftitle.seealso; - See also - array_diff, - array_diff_assoc, - array_diff_uassoc, - array_udiff, - array_udiff_assoc, - array_intersect, - array_intersect_assoc, - array_uintersect, - array_uintersect_assoc and - array_uintersect_uassoc. + + array_diff + array_diff_assoc + array_udiff + array_udiff_uassoc + array_intersect + array_intersect_assoc + array_uintersect + array_uintersect_assoc + array_uintersect_uassoc + diff --git a/reference/array/functions/array-udiff.xml b/reference/array/functions/array-udiff.xml index 3138e66a8f..e6c2b18ccb 100644 --- a/reference/array/functions/array-udiff.xml +++ b/reference/array/functions/array-udiff.xml @@ -1,13 +1,12 @@ - - + array_udiff Computes the difference of arrays by using a callback function for data comparison - - Description + + &reftitle.description; arrayarray_udiff arrayarray1 @@ -16,17 +15,57 @@ callbackdata_compare_func - array_udiff returns an array - containing all the values of array1 - that are not present in any of the other arguments. - Note that keys are preserved. For the comparison of the data - data_compare_func 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 array_diff which uses an + Computes the difference of arrays by using a callback function for data + comparison. This is unlike array_diff which uses an internal function for comparing the data. + + + &reftitle.parameters; + + + + array1 + + + The first array. + + + + + array2 + + + The second array. + + + + + data_compare_func + + + The callback comparison function. + + + 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. + + + + + + + + &reftitle.returnvalues; + + Returns an array containing all the values of array1 + that are not present in any of the other arguments. + + + + &reftitle.examples; <function>array_udiff</function> example @@ -74,6 +113,9 @@ Array + + + &reftitle.notes; Please note that this function only checks one dimension of a n-dimensional @@ -81,18 +123,22 @@ Array array_udiff($array1[0], $array2[0], "data_compare_func");. + + + &reftitle.seealso; - See also - array_diff, - array_diff_assoc, - array_diff_uassoc, - 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_diff_uassoc + array_udiff_assoc + array_udiff_uassoc + array_intersect + array_intersect_assoc + array_uintersect + array_uintersect_assoc + array_uintersect_uassoc + diff --git a/reference/array/functions/array-uintersect-uassoc.xml b/reference/array/functions/array-uintersect-uassoc.xml index 76c815e192..c169bcf3c2 100644 --- a/reference/array/functions/array-uintersect-uassoc.xml +++ b/reference/array/functions/array-uintersect-uassoc.xml @@ -1,12 +1,12 @@ - + array_uintersect_uassoc Computes the intersection of arrays with additional index check, compares data and indexes by a callback functions - - Description + + &reftitle.description; arrayarray_uintersect_uassoc arrayarray1 @@ -16,12 +16,64 @@ callbackkey_compare_func - array_uintersect_uassoc returns an array - containing all the values of array1 - 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 array_uintersect. Both the data and the indexes are compared by using separate callback functions. + + + &reftitle.parameters; + + + + array1 + + + The first array. + + + + + array2 + + + The second array. + + + + + data_compare_func + + + 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. + + + + + key_compare_func + + + Key comparison callback function. + + + + + + + + &reftitle.returnvalues; + + Returns an array containing all the values of + array1 that are present in all the arguments. + + + + &reftitle.examples; <function>array_uintersect_uassoc</function> example @@ -47,18 +99,16 @@ Array + + + &reftitle.seealso; - 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. - - - See also array_uintersect, - array_intersect_assoc, - array_intersect_uassoc and - array_uintersect_assoc. + + array_uintersect + array_intersect_assoc + array_intersect_uassoc + array_uintersect_assoc + diff --git a/reference/array/functions/array-uintersect.xml b/reference/array/functions/array-uintersect.xml index b625a504e1..8d71df8eea 100644 --- a/reference/array/functions/array-uintersect.xml +++ b/reference/array/functions/array-uintersect.xml @@ -1,12 +1,12 @@ - + array_uintersect Computes the intersection of arrays, compares data by a callback function - - Description + + &reftitle.description; arrayarray_uintersect arrayarray1 @@ -15,11 +15,55 @@ callbackdata_compare_func - array_uintersect returns an array - containing all the values of array1 - that are present in all the arguments. - The data is compared by using a callback function. + Computes the intersection of arrays, compares data by a callback function. + + + &reftitle.parameters; + + + + array1 + + + The first array. + + + + + array2 + + + The second array. + + + + + data_compare_func + + + The callback comparison function. + + + 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. + + + + + + + + &reftitle.returnvalues; + + Returns an array containing all the values of array1 + that are present in all the arguments. + + + + &reftitle.examples; <function>array_uintersect</function> example @@ -46,18 +90,16 @@ Array + + + &reftitle.seealso; - 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. - - - See also array_intersect, - array_uintersect_assoc, - array_intersect_uassoc and - array_uintersect_uassoc. + + array_intersect + array_intersect_assoc + array_uintersect_assoc + array_uintersect_uassoc + diff --git a/reference/array/functions/array-walk-recursive.xml b/reference/array/functions/array-walk-recursive.xml index b82a1b5e68..9b18930fa8 100755 --- a/reference/array/functions/array-walk-recursive.xml +++ b/reference/array/functions/array-walk-recursive.xml @@ -1,40 +1,79 @@ - + array_walk_recursive Apply a user function recursively to every member of an array - - Description + + &reftitle.description; boolarray_walk_recursive arrayinput callbackfuncname mixeduserdata - + Applies the user-defined function funcname to each element of the input array. This function will recur - into deeper arrays. Typically, funcname takes on two - parameters. The input parameter's value being the first, and - the key/index second. If the optional userdata - parameter is supplied, it will be passed as the third parameter to - the callback funcname. - - + into deeper arrays. + + + + &reftitle.parameters; + + + + array + + + The input array. + + + + + funcname + + + Typically, funcname takes on two parameters. + The array parameter's value being the first, and + the key/index second. + + + + If funcname needs to be working with the + actual values of the array, specify the first parameter of + funcname as a + reference. Then, + any changes made to those elements will be made in the + original array itself. + + + + + + userdata + + + If the optional userdata parameter is supplied, + it will be passed as the third parameter to the callback + funcname. + + + + + + + + + + &reftitle.returnvalues; + &return.success; - - - - If funcname needs to be working with the - actual values of the array, specify the first parameter of - funcname as a - reference. Then, - any changes made to those elements will be made in the - original array itself. - - + + + + &reftitle.examples; <function>array_walk_recursive</function> example @@ -67,10 +106,15 @@ sour holds lemon - - See also array_walk, and - &seealso.callback;. - + + + &reftitle.seealso; + + + array_walk + &seealso.callback; + + diff --git a/reference/array/functions/array-walk.xml b/reference/array/functions/array-walk.xml index 1c753629b5..bb922583d6 100644 --- a/reference/array/functions/array-walk.xml +++ b/reference/array/functions/array-walk.xml @@ -1,32 +1,88 @@ - - + array_walk Apply a user function to every member of an array - - Description + + &reftitle.description; boolarray_walk arrayarray callbackfuncname mixeduserdata - - &return.success; - Applies the user-defined function funcname to each - element of the array array. Typically, - funcname takes on two parameters. - The array parameter's value being the first, and - the key/index second. If the optional userdata - parameter is supplied, it will be passed as the third parameter to - the callback funcname. + element of the array array. - + + array_walk is not affected by the internal array + pointer of array. array_walk + will walk through the entire array regardless of pointer position. + + + + &reftitle.parameters; + + + + array + + + The input array. + + + + + funcname + + + Typically, funcname takes on two parameters. + The array parameter's value being the first, and + the key/index second. + + + + If funcname needs to be working with the + actual values of the array, specify the first parameter of + funcname as a + reference. Then, + any changes made to those elements will be made in the + original array itself. + + + + Users may not change the array itself from the + callback function. e.g. Add/delete elements, unset elements, etc. If + the array that array_walk is applied to is + changed, the behavior of this function is undefined, and unpredictable. + + + + + userdata + + + If the optional userdata parameter is supplied, + it will be passed as the third parameter to the callback + funcname. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + &reftitle.errors; + If function funcname requires more parameters than given to it, an error of level E_WARNING will be generated each time array_walk @@ -35,36 +91,34 @@ @ to the array_walk call, or by using error_reporting. - - - - If funcname needs to be working with the - actual values of the array, specify the first parameter of - funcname as a - reference. Then, - any changes made to those elements will be made in the - original array itself. - - - - - Passing the key and userdata to funcname was - added in 4.0.0 - - - - array_walk is not affected by the internal - array pointer of array. - array_walk will walk through the entire array - regardless of pointer position. + + + &reftitle.changelog; - Users may not change the array itself from the callback - function. e.g. Add/delete elements, unset elements, etc. If - the array that array_walk is applied to - is changed, the behavior of this function is undefined, and - unpredictable. + + + + + &Version; + &Description; + + + + + 4.0.0 + + Passing the key and userdata to + funcname was added. + + + + + + + + &reftitle.examples; <function>array_walk</function> example @@ -110,16 +164,21 @@ c. fruit: apple - - See also array_walk_recursive, - create_function, - list, - foreach, - each, - call_user_func_array, and - array_map, and - &seealso.callback;. - + + + &reftitle.seealso; + + + array_walk_recursive + create_function + list + each + call_user_func_array + array_map + &seealso.callback; + foreach + + diff --git a/reference/array/functions/array.xml b/reference/array/functions/array.xml index 148c432eec..94b5fb99df 100644 --- a/reference/array/functions/array.xml +++ b/reference/array/functions/array.xml @@ -1,43 +1,57 @@ - - + array Create an array - - Description + + &reftitle.description; arrayarray mixed... + + Creates an array. Read the section on the + array type for more information + on what an array is. + + + + &reftitle.parameters; + + + + ... + + + 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. + + + Having a trailing comma after the last defined array entry, while + unusual, is a valid syntax. + + + + + + + + &reftitle.returnvalues; Returns an array of the parameters. The parameters can be given an index with the => operator. Read the section on the array type for more information on what an array is. - - - - array is a language construct used to - represent literal arrays, and not a regular function. - - - - - 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. - - - Having a trailing comma after the last defined array entry, while - unusual, is a valid syntax. - + + + &reftitle.examples; The following example demonstrates how to create a two-dimensional array, how to specify keys for associative @@ -133,12 +147,29 @@ echo "Hello {$foo['bar']}!"; // Hello baz! + + + &reftitle.notes; - See also array_pad, - list, - count, - foreach, and - range. + + + array is a language construct used to + represent literal arrays, and not a regular function. + + + + + + &reftitle.seealso; + + + array_pad + list + count + range + foreach + The array type + diff --git a/reference/array/functions/compact.xml b/reference/array/functions/compact.xml index 8c4be0cfd7..e717f1f4aa 100644 --- a/reference/array/functions/compact.xml +++ b/reference/array/functions/compact.xml @@ -1,24 +1,19 @@ - - + compact Create array containing variables and their values - - Description + + &reftitle.description; arraycompact mixedvarname mixed... - compact 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; - compact handles it recursively. + Creates an array containing variables and their values. For each of these, compact 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 extract. - It returns the output array with all the variables added to it. Any strings that are not set will simply be skipped. - - Gotcha - - Because variable - variables may not be used with PHP's - Superglobal - arrays within functions, the Superglobal arrays may not be passed - into compact. - - + + + &reftitle.parameters; + + + + varname + + + compact 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; compact + handles it recursively. + + + + + + + + &reftitle.returnvalues; + + Returns the output array with all the variables added to it. + + + + &reftitle.examples; <function>compact</function> example @@ -71,8 +83,26 @@ Array + + + &reftitle.notes; + + Gotcha + + Because variable + variables may not be used with PHP's + Superglobal + arrays within functions, the Superglobal arrays may not be passed + into compact. + + + + + &reftitle.seealso; - See also extract. + + extract + diff --git a/reference/array/functions/extract.xml b/reference/array/functions/extract.xml index 9e621147b0..5ecf396c14 100644 --- a/reference/array/functions/extract.xml +++ b/reference/array/functions/extract.xml @@ -1,13 +1,12 @@ - - + extract Import variables into the current symbol table from an array - - Description + + &reftitle.description; intextract arrayvar_array @@ -15,159 +14,199 @@ stringprefix - This function is used to import variables from an array into the - current symbol table. It takes an associative array - var_array 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 - extract_type and - prefix parameters. + Import variables from an array into the current symbol table. - - - Beginning with version 4.0.5, this function returns the number of - variables extracted. - - - - - EXTR_IF_EXISTS and EXTR_PREFIX_IF_EXISTS were introduced in version 4.2.0. - - - - - EXTR_REFS was introduced in version 4.3.0. - - - extract 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 - extract_type. It can be one of the - following values: + extract checks each key to see whether it has a valid + variable name. It also checks for collisions with existing variables in + the symbol table. + + + + &reftitle.parameters; + - EXTR_OVERWRITE + var_array - - If there is a collision, overwrite the existing variable. - + + 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 + extract_type and + prefix parameters. + + + You must use an associative array, a numerically indexed array + will not produce results unless you use EXTR_PREFIX_ALL or + EXTR_PREFIX_INVALID. + - EXTR_SKIP + extract_type - - If there is a collision, don't overwrite the existing - variable. - + + The way invalid/numeric keys and collisions are treated is determined + by the extract_type. It can be one of the + following values: + + + EXTR_OVERWRITE + + + If there is a collision, overwrite the existing variable. + + + + + EXTR_SKIP + + + If there is a collision, don't overwrite the existing + variable. + + + + + EXTR_PREFIX_SAME + + If there is a collision, prefix the variable name with + prefix. + + + + + EXTR_PREFIX_ALL + + + Prefix all variable names with + prefix. + + + + + EXTR_PREFIX_INVALID + + + Only prefix invalid/numeric variable names with + prefix. + + + + + EXTR_IF_EXISTS + + + 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. + + + + + EXTR_PREFIX_IF_EXISTS + + + Only create prefixed variable names if the non-prefixed version + of the same variable exists in the current symbol table. + + + + + EXTR_REFS + + + Extracts variables as references. This effectively means that the + values of the imported variables are still referencing the values of + the var_array parameter. You can use this flag + on its own or combine it with any other flag by OR'ing the + extract_type. + + + + + + + If extract_type is not specified, it is + assumed to be EXTR_OVERWRITE. + - EXTR_PREFIX_SAME + prefix - If there is a collision, prefix the variable name with - prefix. - - - - - EXTR_PREFIX_ALL - - - Prefix all variable names with - prefix. Beginning with PHP 4.0.5, this includes - numeric variables as well. - - - - - EXTR_PREFIX_INVALID - - - Only prefix invalid/numeric variable names with - prefix. This flag was added in - PHP 4.0.5. - - - - - EXTR_IF_EXISTS - - - 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. - - - - - EXTR_PREFIX_IF_EXISTS - - - 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. - - - - - EXTR_REFS - - - Extracts variables as references. This effectively means that the - values of the imported variables are still referencing the values of - the var_array parameter. You can use this flag - on its own or combine it with any other flag by OR'ing the - extract_type. This flag was added in PHP - 4.3.0. - + + Note that prefix is only required if + extract_type is EXTR_PREFIX_SAME, + EXTR_PREFIX_ALL, EXTR_PREFIX_INVALID + or EXTR_PREFIX_IF_EXISTS. 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. + + + + &reftitle.returnvalues; - If extract_type is not specified, it is - assumed to be EXTR_OVERWRITE. + Returns the number of variables successfully imported into the symbol + table. + + + &reftitle.changelog; - Note that prefix is only required if - extract_type is EXTR_PREFIX_SAME, - EXTR_PREFIX_ALL, EXTR_PREFIX_INVALID - or EXTR_PREFIX_IF_EXISTS. 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. - - - extract returns the number of variables - successfully imported into the symbol table. - - - - Do not use extract on untrusted data, like - user-input ($_GET, ...). If you do, for example, if you want to run old - code that relies on - register_globals - temporarily, make sure you use one of the non-overwriting - extract_type values such as - EXTR_SKIP and be aware that you should extract - in the same order that's defined in - variables_order within the - &php.ini;. - - - - A possible use for extract is to import into the - symbol table variables contained in an associative array returned by - wddx_deserialize. + + + + + &Version; + &Description; + + + + + 4.3.0 + + EXTR_REFS was added. + + + + 4.2.0 + + EXTR_IF_EXISTS and EXTR_PREFIX_IF_EXISTS + were added. + + + + 4.0.5 + + This function now returns the number of variables extracted. + EXTR_PREFIX_INVALID was added. + EXTR_PREFIX_ALL includes numeric variables as well. + + + + + + + + &reftitle.examples; <function>extract</function> example + + A possible use for extract is to import into the + symbol table variables contained in an associative array returned by + wddx_deserialize. + + + The $size wasn't overwritten, because we specified + EXTR_PREFIX_SAME, which resulted in + $wddx_size being created. If EXTR_SKIP was + specified, then $wddx_size wouldn't even have been created. + EXTR_OVERWRITE would have caused $size to have + value "medium", and EXTR_PREFIX_ALL would result in new variables + being named $wddx_color, + $wddx_size, and + $wddx_shape. + + + + &reftitle.notes; + + + Do not use extract on untrusted data, like user-input + ($_GET, ...). If you do, for example, if you want to run old code that + relies on register_globals + temporarily, make sure you use one of the non-overwriting + extract_type values such as + EXTR_SKIP and be aware that you should extract + in the same order that's defined in + variables_order within the + &php.ini;. + + + + + &reftitle.seealso; - The $size wasn't overwritten, because we - specified EXTR_PREFIX_SAME, which resulted in - $wddx_size being created. If EXTR_SKIP was - specified, then $wddx_size wouldn't even have been created. - EXTR_OVERWRITE would have caused $size to have - value "medium", and EXTR_PREFIX_ALL would result in new variables - being named $wddx_color, - $wddx_size, and - $wddx_shape. - - - You must use an associative array, a numerically indexed array - will not produce results unless you use EXTR_PREFIX_ALL or - EXTR_PREFIX_INVALID. - - - See also compact. + + compact +