mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
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
This commit is contained in:
George Peter Banyard
parent
68a9c82e06
commit
9059e4a572
2 changed files with 134 additions and 57 deletions
|
|
@ -38,25 +38,37 @@
|
|||
<listitem>
|
||||
<para>
|
||||
If <parameter>offset</parameter> is non-negative, the sequence will
|
||||
start at that offset in the <parameter>array</parameter>. If
|
||||
<parameter>offset</parameter> is negative, the sequence will
|
||||
start that far from the end of the <parameter>array</parameter>.
|
||||
Note that the <parameter>offset</parameter> denotes the position in the
|
||||
array, not the key.
|
||||
start at that offset in the <parameter>array</parameter>.
|
||||
</para>
|
||||
<para>
|
||||
If <parameter>offset</parameter> is negative, the sequence will
|
||||
start that far from the end of the <parameter>array</parameter>.
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
The <parameter>offset</parameter> parameter denotes the position
|
||||
in the array, not the key.
|
||||
</para>
|
||||
</note>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><parameter>length</parameter></term>
|
||||
<listitem>
|
||||
<para>
|
||||
If <parameter>length</parameter> is given and is positive, then
|
||||
the sequence will have up to that many elements in it. If the array
|
||||
is shorter than the <parameter>length</parameter>, then only the
|
||||
available array elements will be present. If
|
||||
<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
|
||||
If <parameter>length</parameter> is given and is positive,
|
||||
then the sequence will have up to that many elements in it.
|
||||
</para>
|
||||
<para>
|
||||
If the array is shorter than the <parameter>length</parameter>,
|
||||
then only the available array elements will be present.
|
||||
</para>
|
||||
<para>
|
||||
If <parameter>length</parameter> is given and is negative then the
|
||||
sequence will stop that many elements from the end of the array.
|
||||
</para>
|
||||
<para>
|
||||
If it is omitted, then the sequence will have everything
|
||||
from <parameter>offset</parameter> up until the end of the
|
||||
<parameter>array</parameter>.
|
||||
</para>
|
||||
|
|
@ -65,12 +77,14 @@
|
|||
<varlistentry>
|
||||
<term><parameter>preserve_keys</parameter></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Note that <function>array_slice</function> will reorder and reset the
|
||||
integer array indices by default. You can change this behaviour by setting
|
||||
<parameter>preserve_keys</parameter> to &true;.
|
||||
String keys are always preserved, regardless of this parameter.
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
<function>array_slice</function> will reorder and reset the
|
||||
integer array indices by default. This behaviour can be changed
|
||||
by setting <parameter>preserve_keys</parameter> to &true;.
|
||||
String keys are always preserved, regardless of this parameter.
|
||||
</para>
|
||||
</note>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
|
@ -79,7 +93,8 @@
|
|||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1 role="changelog">
|
||||
|
|
@ -97,7 +112,11 @@
|
|||
<row>
|
||||
<entry>5.2.4</entry>
|
||||
<entry>
|
||||
The default value of the <parameter>length</parameter> parameter was changed to <literal>NULL</literal>. A <literal>NULL</literal> <parameter>length</parameter> now tells the function to use the length of <parameter>array</parameter>. Prior to this version, a <literal>NULL</literal> <parameter>length</parameter> was taken to mean a zero length (nothing will be returned).
|
||||
The default value of the <parameter>length</parameter> parameter was
|
||||
changed to &null;. A &null; <parameter>length</parameter> now tells
|
||||
the function to use the length of <parameter>array</parameter>.
|
||||
Prior to this version, a &null; <parameter>length</parameter> was
|
||||
taken to mean a zero length (nothing will be returned).
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
|
|
@ -207,9 +226,9 @@ Array
|
|||
&reftitle.seealso;
|
||||
<para>
|
||||
<simplelist>
|
||||
<member><function>array_chunk</function></member>
|
||||
<member><function>array_splice</function></member>
|
||||
<member><function>unset</function></member>
|
||||
<member><function>array_chunk</function></member>
|
||||
</simplelist>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
|
|
|||
|
|
@ -20,9 +20,11 @@
|
|||
and replaces them with the elements of the
|
||||
<parameter>replacement</parameter> array, if supplied.
|
||||
</para>
|
||||
<para>
|
||||
Note that numeric keys in <parameter>input</parameter> are not preserved.
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
Numerical keys in <parameter>input</parameter> are not preserved.
|
||||
</para>
|
||||
</note>
|
||||
<note>
|
||||
<simpara>
|
||||
If <parameter>replacement</parameter> is not an array, it will be
|
||||
|
|
@ -48,10 +50,13 @@
|
|||
<term><parameter>offset</parameter></term>
|
||||
<listitem>
|
||||
<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
|
||||
If <parameter>offset</parameter> is positive then the start of the
|
||||
removed portion is at that offset from the beginning of the
|
||||
<parameter>input</parameter> array.
|
||||
</para>
|
||||
<para>
|
||||
If <parameter>offset</parameter> is negative then the start of the
|
||||
removed portion is at that offset from the end of the
|
||||
<parameter>input</parameter> array.
|
||||
</para>
|
||||
</listitem>
|
||||
|
|
@ -61,19 +66,28 @@
|
|||
<listitem>
|
||||
<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. If <parameter>length</parameter> is
|
||||
specified and is zero, no elements will be removed.
|
||||
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>.
|
||||
from <parameter>offset</parameter> to the end of the array.
|
||||
</para>
|
||||
<para>
|
||||
If <parameter>length</parameter> is specified and is positive,
|
||||
then that many elements will be removed.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
If <parameter>length</parameter> is specified and is zero,
|
||||
no elements will be removed.
|
||||
</para>
|
||||
<tip>
|
||||
<para>
|
||||
To remove everything from <parameter>offset</parameter> to the end of
|
||||
the array when <parameter>replacement</parameter> is also specified,
|
||||
use <code>count($input)</code> for <parameter>length</parameter>.
|
||||
</para>
|
||||
</tip>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
|
|
@ -87,12 +101,16 @@
|
|||
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>. Note that keys in
|
||||
replacement array are not preserved.
|
||||
specified by the <parameter>offset</parameter>.
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
Keys in the <parameter>replacement</parameter> array are not preserved.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
If <parameter>replacement</parameter> is just one element it is
|
||||
not necessary to put <literal>array()</literal>
|
||||
not necessary to put <literal>array()</literal> or square brackets
|
||||
around it, unless the element is an array itself, an object or &null;.
|
||||
</para>
|
||||
</listitem>
|
||||
|
|
@ -116,36 +134,76 @@
|
|||
<?php
|
||||
$input = array("red", "green", "blue", "yellow");
|
||||
array_splice($input, 2);
|
||||
// $input is now array("red", "green")
|
||||
var_dump($input);
|
||||
|
||||
$input = array("red", "green", "blue", "yellow");
|
||||
array_splice($input, 1, -1);
|
||||
// $input is now array("red", "yellow")
|
||||
var_dump($input);
|
||||
|
||||
$input = array("red", "green", "blue", "yellow");
|
||||
array_splice($input, 1, count($input), "orange");
|
||||
// $input is now array("red", "orange")
|
||||
var_dump($input);
|
||||
|
||||
$input = array("red", "green", "blue", "yellow");
|
||||
array_splice($input, -1, 1, array("black", "maroon"));
|
||||
// $input is now array("red", "green",
|
||||
// "blue", "black", "maroon")
|
||||
|
||||
$input = array("red", "green", "blue", "yellow");
|
||||
array_splice($input, 3, 0, "purple");
|
||||
// $input is now array("red", "green",
|
||||
// "blue", "purple", "yellow");
|
||||
var_dump($input);
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
array(2) {
|
||||
[0]=>
|
||||
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"
|
||||
}
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
<example>
|
||||
<title><function>array_splice</function> examples</title>
|
||||
<title>Equivalent statements to various <function>array_splice</function> examples</title>
|
||||
<para>
|
||||
The following statements change the values of <varname>$input</varname>
|
||||
the same way:
|
||||
The following statements are equivalent:
|
||||
</para>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
|
|
@ -181,9 +239,9 @@ array_splice($input, $x, 1, $y);
|
|||
&reftitle.seealso;
|
||||
<para>
|
||||
<simplelist>
|
||||
<member><function>array_merge</function></member>
|
||||
<member><function>array_slice</function></member>
|
||||
<member><function>unset</function></member>
|
||||
<member><function>array_merge</function></member>
|
||||
</simplelist>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
|
|
|||
Loading…
Reference in a new issue