reference/array/functions/array-splice.xml
cd943f94a013b74df8765ab8e1a620a916a64a85
...
...
@@ -9,20 +9,22 @@
9
9
&reftitle.description;
10
10
<methodsynopsis>
11
11
<type>array</type><methodname>array_splice</methodname>
12
-
<methodparam><type>array</type><parameter role="reference">input</parameter></methodparam>
12
+
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
13
13
<methodparam><type>int</type><parameter>offset</parameter></methodparam>
14
-
<methodparam choice="opt"><type>int</type><parameter>length</parameter><initializer>0</initializer></methodparam>
15
-
<methodparam choice="opt"><type>mixed</type><parameter>replacement</parameter><initializer>array()</initializer></methodparam>
14
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>
15
+
<methodparam choice="opt"><type>mixed</type><parameter>replacement</parameter><initializer>[]</initializer></methodparam>
16
16
</methodsynopsis>
17
17
<para>
18
18
Removes the elements designated by <parameter>offset</parameter> and
19
-
<parameter>length</parameter> from the <parameter>input</parameter> array,
19
+
<parameter>length</parameter> from the <parameter>array</parameter> array,
20
20
and replaces them with the elements of the
21
21
<parameter>replacement</parameter> array, if supplied.
22
22
</para>
23
-
<para>
24
-
Note that numeric keys in <parameter>input</parameter> are not preserved.
25
-
</para>
23
+
<note>
24
+
<para>
25
+
Numerical keys in <parameter>array</parameter> are not preserved.
26
+
</para>
27
+
</note>
26
28
<note>
27
29
<simpara>
28
30
If <parameter>replacement</parameter> is not an array, it will be
...
...
@@ -37,7 +39,7 @@
37
39
<para>
38
40
<variablelist>
39
41
<varlistentry>
40
-
<term><parameter>input</parameter></term>
42
+
<term><parameter>array</parameter></term>
41
43
<listitem>
42
44
<para>
43
45
The input array.
...
...
@@ -48,11 +50,14 @@
48
50
<term><parameter>offset</parameter></term>
49
51
<listitem>
50
52
<para>
51
-
If <parameter>offset</parameter> is positive then the start of removed
52
-
portion is at that offset from the beginning of the
53
-
<parameter>input</parameter> array. If <parameter>offset</parameter>
54
-
is negative then it starts that far from the end of the
55
-
<parameter>input</parameter> array.
53
+
If <parameter>offset</parameter> is positive then the start of the
54
+
removed portion is at that offset from the beginning of the
55
+
<parameter>array</parameter> array.
56
+
</para>
57
+
<para>
58
+
If <parameter>offset</parameter> is negative then the start of the
59
+
removed portion is at that offset from the end of the
60
+
<parameter>array</parameter> array.
56
61
</para>
57
62
</listitem>
58
63
</varlistentry>
...
...
@@ -61,19 +66,28 @@
61
66
<listitem>
62
67
<para>
63
68
If <parameter>length</parameter> is omitted, removes everything
64
-
from <parameter>offset</parameter> to the end of the array. If
65
-
<parameter>length</parameter> is specified and is positive, then
66
-
that many elements will be removed. If
67
-
<parameter>length</parameter> is specified and is negative then
68
-
the end of the removed portion will be that many elements from
69
-
the end of the array. If <parameter>length</parameter> is
70
-
specified and is zero, no elements will be removed.
71
-
Tip: to remove everything from
72
-
<parameter>offset</parameter> to the end of the array when
73
-
<parameter>replacement</parameter> is also specified, use
74
-
<literal>count($input)</literal> for
75
-
<parameter>length</parameter>.
69
+
from <parameter>offset</parameter> to the end of the array.
70
+
</para>
71
+
<para>
72
+
If <parameter>length</parameter> is specified and is positive,
73
+
then that many elements will be removed.
76
74
</para>
75
+
<para>
76
+
If <parameter>length</parameter> is specified and is negative,
77
+
then the end of the removed portion will be that many elements
78
+
from the end of the array.
79
+
</para>
80
+
<para>
81
+
If <parameter>length</parameter> is specified and is zero,
82
+
no elements will be removed.
83
+
</para>
84
+
<tip>
85
+
<para>
86
+
To remove everything from <parameter>offset</parameter> to the end of
87
+
the array when <parameter>replacement</parameter> is also specified,
88
+
use <code>count($input)</code> for <parameter>length</parameter>.
89
+
</para>
90
+
</tip>
77
91
</listitem>
78
92
</varlistentry>
79
93
<varlistentry>
...
...
@@ -87,12 +101,16 @@
87
101
If <parameter>offset</parameter> and <parameter>length</parameter>
88
102
are such that nothing is removed, then the elements from the
89
103
<parameter>replacement</parameter> array are inserted in the place
90
-
specified by the <parameter>offset</parameter>. Note that keys in
91
-
replacement array are not preserved.
104
+
specified by the <parameter>offset</parameter>.
92
105
</para>
106
+
<note>
107
+
<para>
108
+
Keys in the <parameter>replacement</parameter> array are not preserved.
109
+
</para>
110
+
</note>
93
111
<para>
94
112
If <parameter>replacement</parameter> is just one element it is
95
-
not necessary to put <literal>array()</literal>
113
+
not necessary to put <literal>array()</literal> or square brackets
96
114
around it, unless the element is an array itself, an object or &null;.
97
115
</para>
98
116
</listitem>
...
...
@@ -106,6 +124,29 @@
106
124
Returns an array consisting of the extracted elements.
107
125
</para>
108
126
</refsect1>
127
+

128
+
<refsect1 role="changelog">
129
+
&reftitle.changelog;
130
+
<informaltable>
131
+
<tgroup cols="2">
132
+
<thead>
133
+
<row>
134
+
<entry>&Version;</entry>
135
+
<entry>&Description;</entry>
136
+
</row>
137
+
</thead>
138
+
<tbody>
139
+
<row>
140
+
<entry>8.0.0</entry>
141
+
<entry>
142
+
<parameter>length</parameter> is nullable now.
143
+
</entry>
144
+
</row>
145
+
</tbody>
146
+
</tgroup>
147
+
</informaltable>
148
+
</refsect1>
149
+

109
150
<refsect1 role="examples">
110
151
&reftitle.examples;
111
152
<para>
...
...
@@ -116,50 +157,89 @@
116
157
<?php
117
158
$input = array("red", "green", "blue", "yellow");
118
159
array_splice($input, 2);
119
-
// $input is now array("red", "green")
160
+
var_dump($input);
120
161

121
162
$input = array("red", "green", "blue", "yellow");
122
163
array_splice($input, 1, -1);
123
-
// $input is now array("red", "yellow")
164
+
var_dump($input);
124
165

125
166
$input = array("red", "green", "blue", "yellow");
126
167
array_splice($input, 1, count($input), "orange");
127
-
// $input is now array("red", "orange")
168
+
var_dump($input);
128
169

129
170
$input = array("red", "green", "blue", "yellow");
130
171
array_splice($input, -1, 1, array("black", "maroon"));
131
-
// $input is now array("red", "green",
132
-
// "blue", "black", "maroon")
133
-

134
-
$input = array("red", "green", "blue", "yellow");
135
-
array_splice($input, 3, 0, "purple");
136
-
// $input is now array("red", "green",
137
-
// "blue", "purple", "yellow");
172
+
var_dump($input);
138
173
?>
139
174
]]>
140
175
</programlisting>
176
+
&example.outputs;
177
+
<screen>
178
+
<![CDATA[
179
+
array(2) {
180
+
[0]=>
181
+
string(3) "red"
182
+
[1]=>
183
+
string(5) "green"
184
+
}
185
+
array(2) {
186
+
[0]=>
187
+
string(3) "red"
188
+
[1]=>
189
+
string(6) "yellow"
190
+
}
191
+
array(2) {
192
+
[0]=>
193
+
string(3) "red"
194
+
[1]=>
195
+
string(6) "orange"
196
+
}
197
+
array(5) {
198
+
[0]=>
199
+
string(3) "red"
200
+
[1]=>
201
+
string(5) "green"
202
+
[2]=>
203
+
string(4) "blue"
204
+
[3]=>
205
+
string(5) "black"
206
+
[4]=>
207
+
string(6) "maroon"
208
+
}
209
+
]]>
210
+
</screen>
141
211
</example>
142
212
</para>
143
213
<para>
144
214
<example>
145
-
<title><function>array_splice</function> examples</title>
215
+
<title>Equivalent statements to various <function>array_splice</function> examples</title>
146
216
<para>
147
-
The following statements change the values of <varname>$input</varname>
148
-
the same way:
217
+
The following statements are equivalent:
149
218
</para>
150
219
<programlisting role="php">
151
220
<![CDATA[
152
221
<?php
222
+

223
+
// append two elements to $input
153
224
array_push($input, $x, $y);
154
225
array_splice($input, count($input), 0, array($x, $y));
226
+

227
+
// remove the last element of $input
155
228
array_pop($input);
156
229
array_splice($input, -1);
230
+

231
+
// remove the first element of $input
157
232
array_shift($input);
158
233
array_splice($input, 0, 1);
234
+

235
+
// insert an element at the start of $input
159
236
array_unshift($input, $x, $y);
160
237
array_splice($input, 0, 0, array($x, $y));
238
+

239
+
// replace the value in $input at index $x
161
240
$input[$x] = $y; // for arrays where key equals offset
162
241
array_splice($input, $x, 1, $y);
242
+

163
243
?>
164
244
]]>
165
245
</programlisting>
...
...
@@ -170,14 +250,13 @@ array_splice($input, $x, 1, $y);
170
250
&reftitle.seealso;
171
251
<para>
172
252
<simplelist>
253
+
<member><function>array_merge</function></member>
173
254
<member><function>array_slice</function></member>
174
255
<member><function>unset</function></member>
175
-
<member><function>array_merge</function></member>
176
256
</simplelist>
177
257
</para>
178
258
</refsect1>
179
259
</refentry>
180
-

181
260
<!-- Keep this comment at the end of the file
182
261
Local variables:
183
262
mode: sgml
184
263



Tools (Spanish Manual)