reference/array/functions/list.xml
43ac336818cb3a18011d9b6ba91514f3332eb46d
...
...
@@ -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,22 +8,30 @@
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.
19
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>
20
28
</refsect1>
21
29
<refsect1 role="parameters">
22
30
&reftitle.parameters;
23
31
<para>
24
32
<variablelist>
25
33
<varlistentry>
26
-
<term><parameter>varname</parameter></term>
34
+
<term><parameter>var</parameter></term>
27
35
<listitem>
28
36
<para>
29
37
A variable.
...
...
@@ -31,12 +39,52 @@
31
39
</listitem>
32
40
</varlistentry>
33
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>
34
52
</para>
35
53
</refsect1>
36
54
<refsect1 role="returnvalues">
37
55
&reftitle.returnvalues;
38
56
<para>
39
-
&return.void;
57
+
Returns the assigned array.
58
+
</para>
59
+
</refsect1>
60
+
<refsect1 role="changelog">
61
+
&reftitle.changelog;
62
+
<para>
63
+
<informaltable>
64
+
<tgroup cols="2">
65
+
<thead>
66
+
<row>
67
+
<entry>&Version;</entry>
68
+
<entry>&Description;</entry>
69
+
</row>
70
+
</thead>
71
+
<tbody>
72
+
<row>
73
+
<entry>7.3.0</entry>
74
+
<entry>
75
+
Support for reference assignments in array destructuring was added.
76
+
</entry>
77
+
</row>
78
+
<row>
79
+
<entry>7.1.0</entry>
80
+
<entry>
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.
83
+
</entry>
84
+
</row>
85
+
</tbody>
86
+
</tgroup>
87
+
</informaltable>
40
88
</para>
41
89
</refsect1>
42
90
<refsect1 role="examples">
...
...
@@ -75,25 +123,12 @@ var_dump($bar); // NULL
75
123
<title>An example use of <function>list</function></title>
76
124
<programlisting role="php">
77
125
<![CDATA[
78
-
<table>
79
-
<tr>
80
-
<th>Employee name</th>
81
-
<th>Salary</th>
82
-
</tr>
83
-

84
126
<?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";
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";
92
130
}
93
-

94
131
?>
95
-

96
-
</table>
97
132
]]>
98
133
</programlisting>
99
134
</example>
...
...
@@ -123,18 +158,18 @@ int(3)
123
158
</para>
124
159
<para>
125
160
<example>
126
-
<title>Using <function>list</function> with array indices</title>
161
+
<title><function>list</function> and order of index definitions</title>
162
+
<simpara>
163
+
The order in which the indices of the array to be consumed by
164
+
<function>list</function> are defined is irrelevant.
165
+
</simpara>
127
166
<programlisting role="php">
128
167
<![CDATA[
129
168
<?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
-
?>
169
+
$foo = array(2 => 'a', 'foo' => 'b', 0 => 'c');
170
+
$foo[1] = 'd';
171
+
list($x, $y, $z) = $foo;
172
+
var_dump($foo, $x, $y, $z);
138
173
]]>
139
174
</programlisting>
140
175
<para>
...
...
@@ -143,38 +178,60 @@ var_dump($a);
143
178
</para>
144
179
<screen>
145
180
<![CDATA[
146
-
array(3) {
181
+
array(4) {
147
182
[2]=>
148
-
string(8) "caffeine"
149
-
[1]=>
150
-
string(5) "brown"
183
+
string(1) "a"
184
+
["foo"]=>
185
+
string(1) "b"
151
186
[0]=>
152
-
string(6) "coffee"
187
+
string(1) "c"
188
+
[1]=>
189
+
string(1) "d"
153
190
}
191
+
string(1) "c"
192
+
string(1) "d"
193
+
string(1) "a"
194
+
]]>
195
+
</screen>
196
+
</example>
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
154
229
]]>
155
230
</screen>
156
231
</example>
157
232
</para>
158
233
</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>
234
+

178
235
<refsect1 role="seealso">
179
236
&reftitle.seealso;
180
237
<para>
181
238



Tools (Brazilian Portuguese Manual)