reference/array/functions/list.xml
2e60c5134e7a847c99f81eb3f7ecee1f5efeeace
2e60c5134e7a847c99f81eb3f7ecee1f5efeeace
...
...
@@ -9,51 +9,34 @@
9
9
&reftitle.description;
10
10
<methodsynopsis>
11
11
<type>array</type><methodname>list</methodname>
12
-
<methodparam><type>mixed</type><parameter>var1</parameter></methodparam>
13
-
<methodparam rep="repeat" choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
12
+
<methodparam><type>mixed</type><parameter>var</parameter></methodparam>
13
+
<methodparam rep="repeat" choice="opt"><type>mixed</type><parameter>vars</parameter></methodparam>
14
14
</methodsynopsis>
15
15
<para>
16
16
Like <function>array</function>, this is not really a function,
17
-
but a language construct. <function>list</function> is used to
17
+
but a language construct. <function>list</function> is used to
18
18
assign a list of variables in one operation.
19
+
Strings can not be unpacked and <function>list</function> expressions
20
+
can not be completely empty.
19
21
</para>
20
22
<note>
21
23
<para>
22
-
<function>list</function> only works on numerical arrays and assumes
24
+
Before PHP 7.1.0, <function>list</function> only worked on numerical arrays and assumes
23
25
the numerical indices start at 0.
24
26
</para>
25
27
</note>
26
-
<warning>
27
-
<para>
28
-
In PHP 5, <function>list</function> assigns the values starting with the
29
-
right-most parameter. In PHP 7, <function>list</function> starts with the
30
-
left-most parameter.
31
-
</para>
32
-
<para>
33
-
If you are using plain variables, you don't have to worry about this. But
34
-
if you are using arrays with indices you usually expect the order of the
35
-
indices in the array the same you wrote in the <function>list</function>
36
-
from left to right, which is not the case in PHP 5, as it's assigned in the
37
-
reverse order.
38
-
</para>
39
-
<para>
40
-
Generally speaking, it is advisable to avoid relying on a specific order
41
-
of operation, as this may change again in the future.
42
-
</para>
43
-
</warning>
44
-
<warning>
45
-
<para>
46
-
Modification of the array during <function>list</function> execution (e.g.
47
-
using <literal>list($a, $b) = $b</literal>) results in undefined behavior.
48
-
</para>
49
-
</warning>
28
+
<para>
29
+
As of PHP 7.1.0, <function>list</function> can also contain explicit keys, allowing for the
30
+
destructuring of arrays with non-integer or non-sequential keys. For more details on
31
+
array destructuring, see the <link linkend="language.types.array.syntax.destructuring">array destructuring section</link>.
32
+
</para>
50
33
</refsect1>
51
34
<refsect1 role="parameters">
52
35
&reftitle.parameters;
53
36
<para>
54
37
<variablelist>
55
38
<varlistentry>
56
-
<term><parameter>var1</parameter></term>
39
+
<term><parameter>var</parameter></term>
57
40
<listitem>
58
41
<para>
59
42
A variable.
...
...
@@ -61,6 +44,16 @@
61
44
</listitem>
62
45
</varlistentry>
63
46
</variablelist>
47
+
<variablelist>
48
+
<varlistentry>
49
+
<term><parameter>vars</parameter></term>
50
+
<listitem>
51
+
<para>
52
+
Further variables.
53
+
</para>
54
+
</listitem>
55
+
</varlistentry>
56
+
</variablelist>
64
57
</para>
65
58
</refsect1>
66
59
<refsect1 role="returnvalues">
...
...
@@ -82,29 +75,16 @@
82
75
</thead>
83
76
<tbody>
84
77
<row>
85
-
<entry>7.0.0</entry>
78
+
<entry>7.3.0</entry>
86
79
<entry>
87
-
<link linkend="migration70.incompatible.variable-handling.list.order">
88
-
The order that the assignment operations are performed in has
89
-
changed.
90
-
</link>
80
+
Support for reference assignments in array destructuring was added.
91
81
</entry>
92
82
</row>
93
83
<row>
94
-
<entry>7.0.0</entry>
84
+
<entry>7.1.0</entry>
95
85
<entry>
96
-
<link linkend="migration70.incompatible.variable-handling.list.empty">
97
-
<function>list</function> expressions can no longer be completely
98
-
empty.
99
-
</link>
100
-
</entry>
101
-
</row>
102
-
<row>
103
-
<entry>7.0.0</entry>
104
-
<entry>
105
-
<link linkend="migration70.incompatible.variable-handling.list.string">
106
-
Strings can no longer be unpacked.
107
-
</link>
86
+
It is now possible to specify keys in <function>list</function>. This
87
+
enables destructuring of arrays with non-integer or non-sequential keys.
108
88
</entry>
109
89
</row>
110
90
</tbody>
...
...
@@ -146,26 +126,14 @@ var_dump($bar); // NULL
146
126
<para>
147
127
<example>
148
128
<title>An example use of <function>list</function></title>
149
-
<programlisting role="php">
129
+
<programlisting role="php" annotations="non-interactive">
150
130
<![CDATA[
151
-
<table>
152
-
<tr>
153
-
<th>Employee name</th>
154
-
<th>Salary</th>
155
-
</tr>
156
-
157
131
<?php
158
-
$result = $pdo->query("SELECT id, name, salary FROM employees");
159
-
while (list($id, $name, $salary) = $result->fetch(PDO::FETCH_NUM)) {
160
-
echo " <tr>\n" .
161
-
" <td><a href=\"info.php?id=$id\">$name</a></td>\n" .
162
-
" <td>$salary</td>\n" .
163
-
" </tr>\n";
132
+
$result = $pdo->query("SELECT id, name FROM employees");
133
+
while (list($id, $name) = $result->fetch(PDO::FETCH_NUM)) {
134
+
echo "id: $id, name: $name\n";
164
135
}
165
-
166
136
?>
167
-
168
-
</table>
169
137
]]>
170
138
</programlisting>
171
139
</example>
...
...
@@ -184,6 +152,7 @@ var_dump($a, $b, $c);
184
152
?>
185
153
]]>
186
154
</programlisting>
155
+
&example.outputs;
187
156
<screen>
188
157
<![CDATA[
189
158
int(1)
...
...
@@ -194,46 +163,12 @@ int(3)
194
163
</example>
195
164
</para>
196
165
<para>
197
-
<example>
198
-
<title>Using <function>list</function> with array indices</title>
199
-
<programlisting role="php">
200
-
<![CDATA[
201
-
<?php
202
-
203
-
$info = array('coffee', 'brown', 'caffeine');
204
-
205
-
list($a[0], $a[1], $a[2]) = $info;
206
-
207
-
var_dump($a);
208
-
209
-
?>
210
-
]]>
211
-
</programlisting>
212
-
<para>
213
-
Gives the following output (note the order of the elements compared in
214
-
which order they were written in the <function>list</function> syntax):
215
-
</para>
216
-
<screen>
217
-
<![CDATA[
218
-
array(3) {
219
-
[2]=>
220
-
string(8) "caffeine"
221
-
[1]=>
222
-
string(5) "brown"
223
-
[0]=>
224
-
string(6) "coffee"
225
-
}
226
-
]]>
227
-
</screen>
228
-
</example>
166
+
The order in which the indices of the array to be consumed by
167
+
<function>list</function> are defined is irrelevant.
229
168
</para>
230
169
<para>
231
170
<example>
232
171
<title><function>list</function> and order of index definitions</title>
233
-
<simpara>
234
-
The order in which the indices of the array to be consumed by
235
-
<function>list</function> are defined is irrelevant.
236
-
</simpara>
237
172
<programlisting role="php">
238
173
<![CDATA[
239
174
<?php
...
...
@@ -262,6 +197,41 @@ array(4) {
262
197
string(1) "c"
263
198
string(1) "d"
264
199
string(1) "a"
200
+
]]>
201
+
</screen>
202
+
</example>
203
+
</para>
204
+
<para>
205
+
<example>
206
+
<title><function>list</function> with keys</title>
207
+
<simpara>
208
+
As of PHP 7.1.0 <function>list</function> can now also contain
209
+
explicit keys, which can be given as arbitrary expressions.
210
+
Mixing of integer and string keys is allowed; however, elements
211
+
with and without keys cannot be mixed.
212
+
</simpara>
213
+
<programlisting role="php">
214
+
<![CDATA[
215
+
<?php
216
+
$data = [
217
+
["id" => 1, "name" => 'Tom'],
218
+
["id" => 2, "name" => 'Fred'],
219
+
];
220
+
foreach ($data as ["id" => $id, "name" => $name]) {
221
+
echo "id: $id, name: $name\n";
222
+
}
223
+
echo PHP_EOL;
224
+
list(1 => $second, 3 => $fourth) = [1, 2, 3, 4];
225
+
echo "$second, $fourth\n";
226
+
]]>
227
+
</programlisting>
228
+
&example.outputs;
229
+
<screen>
230
+
<![CDATA[
231
+
id: 1, name: Tom
232
+
id: 2, name: Fred
233
+
234
+
2, 4
265
235
]]>
266
236
</screen>
267
237
</example>
268
238