reference/array/functions/array-slice.xml
cd943f94a013b74df8765ab8e1a620a916a64a85
cd943f94a013b74df8765ab8e1a620a916a64a85
...
...
@@ -11,8 +11,8 @@
11
11
<type>array</type><methodname>array_slice</methodname>
12
12
<methodparam><type>array</type><parameter>array</parameter></methodparam>
13
13
<methodparam><type>int</type><parameter>offset</parameter></methodparam>
14
-
<methodparam choice="opt"><type>int</type><parameter>length</parameter><initializer>&null;</initializer></methodparam>
15
-
<methodparam choice="opt"><type>bool</type><parameter>preserve_keys</parameter><initializer>false</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>bool</type><parameter>preserve_keys</parameter><initializer>&false;</initializer></methodparam>
16
16
</methodsynopsis>
17
17
<para>
18
18
<function>array_slice</function> returns the sequence of elements
...
...
@@ -38,23 +38,37 @@
38
38
<listitem>
39
39
<para>
40
40
If <parameter>offset</parameter> is non-negative, the sequence will
41
-
start at that offset in the <parameter>array</parameter>. If
42
-
<parameter>offset</parameter> is negative, the sequence will
41
+
start at that offset in the <parameter>array</parameter>.
42
+
</para>
43
+
<para>
44
+
If <parameter>offset</parameter> is negative, the sequence will
43
45
start that far from the end of the <parameter>array</parameter>.
44
46
</para>
47
+
<note>
48
+
<para>
49
+
The <parameter>offset</parameter> parameter denotes the position
50
+
in the array, not the key.
51
+
</para>
52
+
</note>
45
53
</listitem>
46
54
</varlistentry>
47
55
<varlistentry>
48
56
<term><parameter>length</parameter></term>
49
57
<listitem>
50
58
<para>
51
-
If <parameter>length</parameter> is given and is positive, then
52
-
the sequence will have up to that many elements in it. If the array
53
-
is shorter than the <parameter>length</parameter>, then only the
54
-
available array elements will be present. If
55
-
<parameter>length</parameter> is given and is negative then the
56
-
sequence will stop that many elements from the end of the
57
-
array. If it is omitted, then the sequence will have everything
59
+
If <parameter>length</parameter> is given and is positive,
60
+
then the sequence will have up to that many elements in it.
61
+
</para>
62
+
<para>
63
+
If the array is shorter than the <parameter>length</parameter>,
64
+
then only the available array elements will be present.
65
+
</para>
66
+
<para>
67
+
If <parameter>length</parameter> is given and is negative then the
68
+
sequence will stop that many elements from the end of the array.
69
+
</para>
70
+
<para>
71
+
If it is omitted, then the sequence will have everything
58
72
from <parameter>offset</parameter> up until the end of the
59
73
<parameter>array</parameter>.
60
74
</para>
...
...
@@ -63,11 +77,14 @@
63
77
<varlistentry>
64
78
<term><parameter>preserve_keys</parameter></term>
65
79
<listitem>
66
-
<para>
67
-
Note that <function>array_slice</function> will reorder and reset the
68
-
numeric array indices by default. You can change this behaviour by setting
69
-
<parameter>preserve_keys</parameter> to &true;.
70
-
</para>
80
+
<note>
81
+
<para>
82
+
<function>array_slice</function> will reorder and reset the
83
+
integer array indices by default. This behaviour can be changed
84
+
by setting <parameter>preserve_keys</parameter> to &true;.
85
+
String keys are always preserved, regardless of this parameter.
86
+
</para>
87
+
</note>
71
88
</listitem>
72
89
</varlistentry>
73
90
</variablelist>
...
...
@@ -76,36 +93,8 @@
76
93
<refsect1 role="returnvalues">
77
94
&reftitle.returnvalues;
78
95
<para>
79
-
Returns the slice. If the offset is larger than the size of the array then returns an empty array.
80
-
</para>
81
-
</refsect1>
82
-
<refsect1 role="changelog">
83
-
&reftitle.changelog;
84
-
<para>
85
-
<informaltable>
86
-
<tgroup cols="2">
87
-
<thead>
88
-
<row>
89
-
<entry>&Version;</entry>
90
-
<entry>&Description;</entry>
91
-
</row>
92
-
</thead>
93
-
<tbody>
94
-
<row>
95
-
<entry>5.2.4</entry>
96
-
<entry>
97
-
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).
98
-
</entry>
99
-
</row>
100
-
<row>
101
-
<entry>5.0.2</entry>
102
-
<entry>
103
-
The optional <parameter>preserve_keys</parameter> parameter was added.
104
-
</entry>
105
-
</row>
106
-
</tbody>
107
-
</tgroup>
108
-
</informaltable>
96
+
Returns the slice. If the offset is larger than the size of the array,
97
+
an empty array is returned.
109
98
</para>
110
99
</refsect1>
111
100
<refsect1 role="examples">
...
...
@@ -145,19 +134,72 @@ Array
145
134
</screen>
146
135
</example>
147
136
</para>
137
+
<para>
138
+
<example>
139
+
<title><function>array_slice</function> and one-based array</title>
140
+
<programlisting role="php">
141
+
<![CDATA[
142
+
<?php
143
+
$input = array(1 => "a", "b", "c", "d", "e");
144
+
print_r(array_slice($input, 1, 2));
145
+
?>
146
+
]]>
147
+
</programlisting>
148
+
&example.outputs;
149
+
<screen>
150
+
<![CDATA[
151
+
Array
152
+
(
153
+
[0] => b
154
+
[1] => c
155
+
)
156
+
]]>
157
+
</screen>
158
+
</example>
159
+
</para>
160
+
<para>
161
+
<example>
162
+
<title><function>array_slice</function> and array with mixed keys</title>
163
+
<programlisting role="php">
164
+
<![CDATA[
165
+
<?php
166
+
$ar = array('a'=>'apple', 'b'=>'banana', '42'=>'pear', 'd'=>'orange');
167
+
print_r(array_slice($ar, 0, 3));
168
+
print_r(array_slice($ar, 0, 3, true));
169
+
?>
170
+
]]>
171
+
</programlisting>
172
+
&example.outputs;
173
+
<screen>
174
+
<![CDATA[
175
+
Array
176
+
(
177
+
[a] => apple
178
+
[b] => banana
179
+
[0] => pear
180
+
)
181
+
Array
182
+
(
183
+
[a] => apple
184
+
[b] => banana
185
+
[42] => pear
186
+
)
187
+
]]>
188
+
</screen>
189
+
</example>
190
+
</para>
148
191
</refsect1>
149
192
<refsect1 role="seealso">
150
193
&reftitle.seealso;
151
194
<para>
152
195
<simplelist>
196
+
<member><function>array_chunk</function></member>
153
197
<member><function>array_splice</function></member>
154
198
<member><function>unset</function></member>
155
-
<member><function>array_chunk</function></member>
156
199
</simplelist>
157
200
</para>
158
201
</refsect1>
159
202
</refentry>
160
-
161
203
<!-- Keep this comment at the end of the file
162
204
Local variables:
163
205
mode: sgml
164
206