reference/array/functions/list.xml
43ac336818cb3a18011d9b6ba91514f3332eb46d
...
...
@@ -9,51 +9,29 @@
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>
50
28
</refsect1>
51
29
<refsect1 role="parameters">
52
30
&reftitle.parameters;
53
31
<para>
54
32
<variablelist>
55
33
<varlistentry>
56
-
<term><parameter>var1</parameter></term>
34
+
<term><parameter>var</parameter></term>
57
35
<listitem>
58
36
<para>
59
37
A variable.
...
...
@@ -61,6 +39,16 @@
61
39
</listitem>
62
40
</varlistentry>
63
41
</variablelist>
42
+
<variablelist>
43
+
<varlistentry>
44
+
<term><parameter>vars</parameter></term>
45
+
<listitem>
46
+
<para>
47
+
Further variables.
48
+
</para>
49
+
</listitem>
50
+
</varlistentry>
51
+
</variablelist>
64
52
</para>
65
53
</refsect1>
66
54
<refsect1 role="returnvalues">
...
...
@@ -82,29 +70,16 @@
82
70
</thead>
83
71
<tbody>
84
72
<row>
85
-
<entry>7.0.0</entry>
86
-
<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>
91
-
</entry>
92
-
</row>
93
-
<row>
94
-
<entry>7.0.0</entry>
73
+
<entry>7.3.0</entry>
95
74
<entry>
96
-
<link linkend="migration70.incompatible.variable-handling.list.empty">
97
-
<function>list</function> expressions can no longer be completely
98
-
empty.
99
-
</link>
75
+
Support for reference assignments in array destructuring was added.
100
76
</entry>
101
77
</row>
102
78
<row>
103
-
<entry>7.0.0</entry>
79
+
<entry>7.1.0</entry>
104
80
<entry>
105
-
<link linkend="migration70.incompatible.variable-handling.list.string">
106
-
Strings can no longer be unpacked.
107
-
</link>
81
+
It is now possible to specify keys in <function>list</function>. This
82
+
enables destructuring of arrays with non-integer or non-sequential keys.
108
83
</entry>
109
84
</row>
110
85
</tbody>
...
...
@@ -148,24 +123,12 @@ var_dump($bar); // NULL
148
123
<title>An example use of <function>list</function></title>
149
124
<programlisting role="php">
150
125
<![CDATA[
151
-
<table>
152
-
<tr>
153
-
<th>Employee name</th>
154
-
<th>Salary</th>
155
-
</tr>
156
-

157
126
<?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";
127
+
$result = $pdo->query("SELECT id, name FROM employees");
128
+
while (list($id, $name) = $result->fetch(PDO::FETCH_NUM)) {
129
+
echo "id: $id, name: $name\n";
164
130
}
165
-

166
131
?>
167
-

168
-
</table>
169
132
]]>
170
133
</programlisting>
171
134
</example>
...
...
@@ -195,40 +158,6 @@ int(3)
195
158
</para>
196
159
<para>
197
160
<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>
229
-
</para>
230
-
<para>
231
-
<example>
232
161
<title><function>list</function> and order of index definitions</title>
233
162
<simpara>
234
163
The order in which the indices of the array to be consumed by
...
...
@@ -266,6 +195,41 @@ string(1) "a"
266
195
</screen>
267
196
</example>
268
197
</para>
198
+
<para>
199
+
<example>
200
+
<title><function>list</function> with keys</title>
201
+
<simpara>
202
+
As of PHP 7.1.0 <function>list</function> can now also contain
203
+
explicit keys, which can be given as arbitrary expressions.
204
+
Mixing of integer and string keys is allowed; however, elements
205
+
with and without keys cannot be mixed.
206
+
</simpara>
207
+
<programlisting role="php">
208
+
<![CDATA[
209
+
<?php
210
+
$data = [
211
+
["id" => 1, "name" => 'Tom'],
212
+
["id" => 2, "name" => 'Fred'],
213
+
];
214
+
foreach ($data as ["id" => $id, "name" => $name]) {
215
+
echo "id: $id, name: $name\n";
216
+
}
217
+
echo PHP_EOL;
218
+
list(1 => $second, 3 => $fourth) = [1, 2, 3, 4];
219
+
echo "$second, $fourth\n";
220
+
]]>
221
+
</programlisting>
222
+
&example.outputs;
223
+
<screen>
224
+
<![CDATA[
225
+
id: 1, name: Tom
226
+
id: 2, name: Fred
227
+

228
+
2, 4
229
+
]]>
230
+
</screen>
231
+
</example>
232
+
</para>
269
233
</refsect1>
270
234

271
235
<refsect1 role="seealso">
272
236