reference/array/functions/list.xml
2e60c5134e7a847c99f81eb3f7ecee1f5efeeace
...
...
@@ -1,4 +1,4 @@
1
-
<?xml version="1.0" encoding="iso-8859-1"?>
1
+
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
3
<refentry xml:id="function.list" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
...
...
@@ -8,14 +8,27 @@
8
8
<refsect1 role="description">
9
9
&reftitle.description;
10
10
<methodsynopsis>
11
-
<type>void</type><methodname>list</methodname>
12
-
<methodparam><type>mixed</type><parameter>varname</parameter></methodparam>
13
-
<methodparam rep="repeat" choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
11
+
<type>array</type><methodname>list</methodname>
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.
21
+
</para>
22
+
<note>
23
+
<para>
24
+
Before PHP 7.1.0, <function>list</function> only worked on numerical arrays and assumes
25
+
the numerical indices start at 0.
26
+
</para>
27
+
</note>
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>.
19
32
</para>
20
33
</refsect1>
21
34
<refsect1 role="parameters">
...
...
@@ -23,7 +36,7 @@
23
36
<para>
24
37
<variablelist>
25
38
<varlistentry>
26
-
<term><parameter>varname</parameter></term>
39
+
<term><parameter>var</parameter></term>
27
40
<listitem>
28
41
<para>
29
42
A variable.
...
...
@@ -31,12 +44,52 @@
31
44
</listitem>
32
45
</varlistentry>
33
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>
34
57
</para>
35
58
</refsect1>
36
59
<refsect1 role="returnvalues">
37
60
&reftitle.returnvalues;
38
61
<para>
39
-
&return.void;
62
+
Returns the assigned array.
63
+
</para>
64
+
</refsect1>
65
+
<refsect1 role="changelog">
66
+
&reftitle.changelog;
67
+
<para>
68
+
<informaltable>
69
+
<tgroup cols="2">
70
+
<thead>
71
+
<row>
72
+
<entry>&Version;</entry>
73
+
<entry>&Description;</entry>
74
+
</row>
75
+
</thead>
76
+
<tbody>
77
+
<row>
78
+
<entry>7.3.0</entry>
79
+
<entry>
80
+
Support for reference assignments in array destructuring was added.
81
+
</entry>
82
+
</row>
83
+
<row>
84
+
<entry>7.1.0</entry>
85
+
<entry>
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.
88
+
</entry>
89
+
</row>
90
+
</tbody>
91
+
</tgroup>
92
+
</informaltable>
40
93
</para>
41
94
</refsect1>
42
95
<refsect1 role="examples">
...
...
@@ -73,27 +126,14 @@ var_dump($bar); // NULL
73
126
<para>
74
127
<example>
75
128
<title>An example use of <function>list</function></title>
76
-
<programlisting role="php">
129
+
<programlisting role="php" annotations="non-interactive">
77
130
<![CDATA[
78
-
<table>
79
-
<tr>
80
-
<th>Employee name</th>
81
-
<th>Salary</th>
82
-
</tr>
83
-

84
131
<?php
85
-

86
-
$result = mysql_query("SELECT id, name, salary FROM employees", $conn);
87
-
while (list($id, $name, $salary) = mysql_fetch_row($result)) {
88
-
echo " <tr>\n" .
89
-
" <td><a href=\"info.php?id=$id\">$name</a></td>\n" .
90
-
" <td>$salary</td>\n" .
91
-
" </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";
92
135
}
93
-

94
136
?>
95
-

96
-
</table>
97
137
]]>
98
138
</programlisting>
99
139
</example>
...
...
@@ -112,6 +152,7 @@ var_dump($a, $b, $c);
112
152
?>
113
153
]]>
114
154
</programlisting>
155
+
&example.outputs;
115
156
<screen>
116
157
<![CDATA[
117
158
int(1)
...
...
@@ -121,20 +162,20 @@ int(3)
121
162
</screen>
122
163
</example>
123
164
</para>
165
+
<para>
166
+
The order in which the indices of the array to be consumed by
167
+
<function>list</function> are defined is irrelevant.
168
+
</para>
124
169
<para>
125
170
<example>
126
-
<title>Using <function>list</function> with array indices</title>
171
+
<title><function>list</function> and order of index definitions</title>
127
172
<programlisting role="php">
128
173
<![CDATA[
129
174
<?php
130
-

131
-
$info = array('coffee', 'brown', 'caffeine');
132
-

133
-
list($a[0], $a[1], $a[2]) = $info;
134
-

135
-
var_dump($a);
136
-

137
-
?>
175
+
$foo = array(2 => 'a', 'foo' => 'b', 0 => 'c');
176
+
$foo[1] = 'd';
177
+
list($x, $y, $z) = $foo;
178
+
var_dump($foo, $x, $y, $z);
138
179
]]>
139
180
</programlisting>
140
181
<para>
...
...
@@ -143,38 +184,60 @@ var_dump($a);
143
184
</para>
144
185
<screen>
145
186
<![CDATA[
146
-
array(3) {
187
+
array(4) {
147
188
[2]=>
148
-
string(8) "caffeine"
149
-
[1]=>
150
-
string(5) "brown"
189
+
string(1) "a"
190
+
["foo"]=>
191
+
string(1) "b"
151
192
[0]=>
152
-
string(6) "coffee"
193
+
string(1) "c"
194
+
[1]=>
195
+
string(1) "d"
153
196
}
197
+
string(1) "c"
198
+
string(1) "d"
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
154
235
]]>
155
236
</screen>
156
237
</example>
157
238
</para>
158
239
</refsect1>
159
-
<refsect1 role="notes">
160
-
&reftitle.notes;
161
-
<warning>
162
-
<para>
163
-
<function>list</function> assigns the values starting with the right-most
164
-
parameter. If you are using plain variables, you don't have to worry
165
-
about this. But if you are using arrays with indices you usually expect
166
-
the order of the indices in the array the same you wrote in the
167
-
<function>list</function> from left to right; which it isn't. It's
168
-
assigned in the reverse order.
169
-
</para>
170
-
</warning>
171
-
<note>
172
-
<para>
173
-
<function>list</function> only works on numerical arrays and assumes
174
-
the numerical indices start at 0.
175
-
</para>
176
-
</note>
177
-
</refsect1>
240
+

178
241
<refsect1 role="seealso">
179
242
&reftitle.seealso;
180
243
<para>
181
244



Translation status