From 9059e4a572ec6197cbec1616a1a5fd96fb760737 Mon Sep 17 00:00:00 2001 From: George Peter Banyard Date: Mon, 1 Apr 2019 20:22:42 +0000 Subject: [PATCH] Improve array_slice and array_splice documentation pages. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@347119 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/array/functions/array-slice.xml | 61 ++++++---- reference/array/functions/array-splice.xml | 130 +++++++++++++++------ 2 files changed, 134 insertions(+), 57 deletions(-) diff --git a/reference/array/functions/array-slice.xml b/reference/array/functions/array-slice.xml index 21b1ef0efb..ac563e4288 100644 --- a/reference/array/functions/array-slice.xml +++ b/reference/array/functions/array-slice.xml @@ -38,25 +38,37 @@ If offset is non-negative, the sequence will - start at that offset in the array. If - offset is negative, the sequence will - start that far from the end of the array. - Note that the offset denotes the position in the - array, not the key. + start at that offset in the array. + + If offset is negative, the sequence will + start that far from the end of the array. + + + + The offset parameter denotes the position + in the array, not the key. + + length - If length is given and is positive, then - the sequence will have up to that many elements in it. If the array - is shorter than the length, then only the - available array elements will be present. If - length is given and is negative then the - sequence will stop that many elements from the end of the - array. If it is omitted, then the sequence will have everything + If length is given and is positive, + then the sequence will have up to that many elements in it. + + + If the array is shorter than the length, + then only the available array elements will be present. + + + If length is given and is negative then the + sequence will stop that many elements from the end of the array. + + + If it is omitted, then the sequence will have everything from offset up until the end of the array. @@ -65,12 +77,14 @@ preserve_keys - - Note that array_slice will reorder and reset the - integer array indices by default. You can change this behaviour by setting - preserve_keys to &true;. - String keys are always preserved, regardless of this parameter. - + + + array_slice will reorder and reset the + integer array indices by default. This behaviour can be changed + by setting preserve_keys to &true;. + String keys are always preserved, regardless of this parameter. + + @@ -79,7 +93,8 @@ &reftitle.returnvalues; - Returns the slice. If the offset is larger than the size of the array then returns an empty array. + Returns the slice. If the offset is larger than the size of the array, + an empty array is returned. @@ -97,7 +112,11 @@ 5.2.4 - The default value of the length parameter was changed to NULL. A NULL length now tells the function to use the length of array. Prior to this version, a NULL length was taken to mean a zero length (nothing will be returned). + The default value of the length parameter was + changed to &null;. A &null; length now tells + the function to use the length of array. + Prior to this version, a &null; length was + taken to mean a zero length (nothing will be returned). @@ -207,9 +226,9 @@ Array &reftitle.seealso; + array_chunk array_splice unset - array_chunk diff --git a/reference/array/functions/array-splice.xml b/reference/array/functions/array-splice.xml index dd1135f498..90f2bae703 100644 --- a/reference/array/functions/array-splice.xml +++ b/reference/array/functions/array-splice.xml @@ -20,9 +20,11 @@ and replaces them with the elements of the replacement array, if supplied. - - Note that numeric keys in input are not preserved. - + + + Numerical keys in input are not preserved. + + If replacement is not an array, it will be @@ -48,10 +50,13 @@ 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 + If offset is positive then the start of the + removed portion is at that offset from the beginning of the + input array. + + + If offset is negative then the start of the + removed portion is at that offset from the end of the input array. @@ -61,19 +66,28 @@ 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. If length is - specified and is zero, no elements will be removed. - Tip: to remove everything from - offset to the end of the array when - replacement is also specified, use - count($input) for - length. + 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. + + + If length is specified and is zero, + no elements will be removed. + + + + To remove everything from offset to the end of + the array when replacement is also specified, + use count($input) for length. + + @@ -87,12 +101,16 @@ 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. + specified by the offset. + + + Keys in the replacement array are not preserved. + + If replacement is just one element it is - not necessary to put array() + not necessary to put array() or square brackets around it, unless the element is an array itself, an object or &null;. @@ -116,36 +134,76 @@ ]]> + &example.outputs; + + + string(3) "red" + [1]=> + string(5) "green" +} +array(2) { + [0]=> + string(3) "red" + [1]=> + string(6) "yellow" +} +array(2) { + [0]=> + string(3) "red" + [1]=> + string(6) "orange" +} +array(5) { + [0]=> + string(3) "red" + [1]=> + string(5) "green" + [2]=> + string(4) "blue" + [3]=> + string(5) "black" + [4]=> + string(6) "maroon" +} +array(5) { + [0]=> + string(3) "red" + [1]=> + string(5) "green" + [2]=> + string(4) "blue" + [3]=> + string(6) "purple" + [4]=> + string(6) "yellow" +} +]]> + - <function>array_splice</function> examples + Equivalent statements to various <function>array_splice</function> examples - The following statements change the values of $input - the same way: + The following statements are equivalent: + array_merge array_slice unset - array_merge