cvs: /phpdoc/functions array.sgml

andrey Fri Jul 16 17:12:20 1999 EDT Modified files: /phpdoc/functions array.sgml Log: array_splice documented Index: phpdoc/functions/array.sgml diff -u phpdoc/functions/array.sgml:1.8 phpdoc/functions/array.sgml:1.9 --- phpdoc/functions/array.sgml:1.8 Fri Jul 16 16:51:08 1999 +++ phpdoc/functions/array.sgml Fri Jul 16 17:12:20 1999 @@ -258,15 +258,15 @@ If <parameter>offset</parameter> is positive, the sequence will start at that offset in the <parameter>array</parameter>. If <parameter>offset</parameter> is negative, the sequence will - start at that offset from the end of the - <parameter>array</parameter>. + start that far from the end of the <parameter>array</parameter>. <para> If <parameter>length</parameter> is given and is positive, then the sequence will have that many elements in it. If - <parameter>length</parameter> is given and is negative or if it - is omitted, then the sequence will have everything from - <parameter>offset</parameter> and up until the end of the + <parameter>length</parameter> 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 <parameter>offset</parameter> up until the end of the <parameter>array</parameter>. <para> @@ -276,7 +276,7 @@ $input = array("a", "b", "c", "d", "e"); $output = array_slice($input, 2); // returns "c", "d", and "e" -$output = array_slice($input, 2, -1); // returns "c", "d", and "e" +$output = array_slice($input, 2, -1); // returns "c", "d" $output = array_slice($input, -2, 1); // returns "d" $output = array_slice($input, 0, 3); // returns "a", "b", and "c" </programlisting> @@ -291,6 +291,87 @@ </note> </refsect1> </refentry> + + <refentry id="function.array-splice"> + <refnamediv> + <refname>array_splice</refname> + <refpurpose>Remove a portion of the array and replace it with something else</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcdef>array <function>array_splice</function></funcdef> + <paramdef>array <parameter>input</parameter></paramdef> + <paramdef>int <parameter>offset</parameter></paramdef> + <paramdef>int + <parameter><optional>length</optional></parameter></paramdef> + <paramdef>array + <parameter><optional>replacement</optional></parameter></paramdef> + </funcsynopsis> + + <para> + <function>array_splice</function> removed the elements designated + by <parameter>offset</parameter> and + <parameter>length</parameter> from the + <parameter>input</parameter> array, and replaces them with the + elements of the <parameter>replacement</parameter> array, if supplied. + + <para> + If <parameter>offset</parameter> is positive then the start of + removed portion is at that offset from the beginning of the + <parameter>input</parameter> array. If + <parameter>offset</parameter> is negative then it starts that far + from the end of the <parameter>input</parameter> array. + + <para> + If <parameter>length</parameter> is omitted, removes everything + from <parameter>offset</parameter> to the end of the array. If + <parameter>length</parameter> is specified and is positive, then + that many elements will be removed. If + <parameter>length</parameter> is specified and is negative then + the end of the removed portion will be that many elements from + the end of the array. Tip: to remove everything from + <parameter>offset</parameter> to the end of the array when + <parameter>replacement</parameter> is also specified, use + <literal>count($input)</literal> for + <parameter>length</parameter>. + + <para> + If <parameter>replacement</parameter> array is specified, then + the removed elements are replaced with elements from this array. If <parameter>offset</parameter> and <parameter>length</parameter> are such that nothing is removed, then the elements from the <parameter>replacement</parameter> array are inserted in the place specified by the <parameter>offset</parameter>. Tip: if the replacement is just one element it is not necessary to put <literal>array()</literal> around it, unless the element is an array itself. + + <para> + The following equivalences hold: + <programlisting> +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)) +$a[$x] = $y array_splice($input, $x, 1, $y) + </programlisting> + + <para> + Returns the array consisting of removed elements. + + <para> + <example> + <title><function>array_splice</function> examples</title> + <programlisting> +$input = array("red", "green", "blue", "yellow"); + +array_splice($input, 2); // $input is now array("red", "green") +array_splice($input, 1, -1); // $input is now array("red", "yellow") +array_splice($input, 1, count($input), "orange"); // $input is now array("red", "orange") +array_splice($input, -1, 1, array("black", "maroon")); // $input is now array("red", "green", "blue", "black", "maroon") + </programlisting> + </example> + + <para> + See also <function>array_slice</function>. + </refsect1> + </refentry> + + <refentry id="function.array-walk"> <refnamediv>