reference/array/functions/array-map.xml
2e60c5134e7a847c99f81eb3f7ecee1f5efeeace
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.array-map">
3
+
<refentry xml:id="function.array-map" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>array_map</refname>
6
6
<refpurpose>Applies the callback to the elements of the given arrays</refpurpose>
...
...
@@ -10,18 +10,21 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>array</type><methodname>array_map</methodname>
13
-
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
14
-
<methodparam><type>array</type><parameter>array1</parameter></methodparam>
15
-
<methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam>
13
+
<methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>
14
+
<methodparam><type>array</type><parameter>array</parameter></methodparam>
15
+
<methodparam rep="repeat"><type>array</type><parameter>arrays</parameter></methodparam>
16
16
</methodsynopsis>
17
17
<para>
18
-
<function>array_map</function> returns an array containing all
19
-
the elements of <parameter>array1</parameter> after applying the
20
-
<parameter>callback</parameter> function to each one.
18
+
<function>array_map</function> returns an &array; containing
19
+
the results of applying the <parameter>callback</parameter>
20
+
to the corresponding value of <parameter>array</parameter>
21
+
(and <parameter>arrays</parameter> if more arrays are provided)
22
+
used as arguments for the callback.
21
23
The number of parameters that the <parameter>callback</parameter>
22
-
function accepts
23
-
should match the number of arrays
24
-
passed to the <function>array_map</function>
24
+
function accepts should match the number of arrays
25
+
passed to <function>array_map</function>. Excess
26
+
input arrays are ignored. An <classname>ArgumentCountError</classname>
27
+
is thrown if an insufficient number of arguments is provided.
25
28
</para>
26
29
</refsect1>
27
30

...
...
@@ -33,12 +36,19 @@
33
36
<term><parameter>callback</parameter></term>
34
37
<listitem>
35
38
<para>
36
-
Callback function to run for each element in each array.
39
+
A <type>callable</type> to run for each element in each array.
40
+
</para>
41
+
<para>
42
+
&null; can be passed as a value to <parameter>callback</parameter>
43
+
to perform a zip operation on multiple arrays and return an array
44
+
whose elements are each an array holding the elements of the input arrays of the same index (see example below).
45
+
If only <parameter>array</parameter> is provided,
46
+
<methodname>array_map</methodname> will return the input array.
37
47
</para>
38
48
</listitem>
39
49
</varlistentry>
40
50
<varlistentry>
41
-
<term><parameter>array1</parameter></term>
51
+
<term><parameter>array</parameter></term>
42
52
<listitem>
43
53
<para>
44
54
An array to run through the <parameter>callback</parameter> function.
...
...
@@ -46,10 +56,10 @@
46
56
</listitem>
47
57
</varlistentry>
48
58
<varlistentry>
49
-
<term><parameter>...</parameter></term>
59
+
<term><parameter>arrays</parameter></term>
50
60
<listitem>
51
61
<para>
52
-
Variable list of array arguments to run through the
62
+
Supplementary variable list of array arguments to run through the
53
63
<parameter>callback</parameter> function.
54
64
</para>
55
65
</listitem>
...
...
@@ -61,11 +71,35 @@
61
71
<refsect1 role="returnvalues">
62
72
&reftitle.returnvalues;
63
73
<para>
64
-
Returns an array containing all the elements of <parameter>array1</parameter>
65
-
after applying the <parameter>callback</parameter> function to each one.
74
+
Returns an array containing the results of applying the <parameter>callback</parameter>
75
+
function to the corresponding value of <parameter>array</parameter>
76
+
(and <parameter>arrays</parameter> if more arrays are provided)
77
+
used as arguments for the callback.
78
+
</para>
79
+
<para>
80
+
The returned array will preserve the keys of the array argument if and only
81
+
if exactly one array is passed. If more than one array is passed, the
82
+
returned array will have sequential integer keys.
66
83
</para>
67
84
</refsect1>
68
85

86
+
<refsect1 role="changelog">
87
+
&reftitle.changelog;
88
+
<informaltable>
89
+
<tgroup cols="2">
90
+
<thead>
91
+
<row>
92
+
<entry>&Version;</entry>
93
+
<entry>&Description;</entry>
94
+
</row>
95
+
</thead>
96
+
<tbody>
97
+
&array.changelog.by-ref;
98
+
</tbody>
99
+
</tgroup>
100
+
</informaltable>
101
+
</refsect1>
102
+

69
103
<refsect1 role="examples">
70
104
&reftitle.examples;
71
105
<para>
...
...
@@ -76,11 +110,11 @@
76
110
<?php
77
111
function cube($n)
78
112
{
79
-
return($n * $n * $n);
113
+
return ($n * $n * $n);
80
114
}
81
115

82
-
$a = array(1, 2, 3, 4, 5);
83
-
$b = array_map("cube", $a);
116
+
$a = [1, 2, 3, 4, 5];
117
+
$b = array_map('cube', $a);
84
118
print_r($b);
85
119
?>
86
120
]]>
...
...
@@ -104,18 +138,24 @@ Array
104
138
</para>
105
139
<para>
106
140
<example>
107
-
<title><function>array_map</function> using a lambda function (as of PHP 5.3.0)</title>
141
+
<title><function>array_map</function> using a lambda function</title>
108
142
<programlisting role="php">
109
143
<![CDATA[
110
144
<?php
111
-
$func = function($value) {
145
+
$func = function(int $value): int {
112
146
return $value * 2;
113
147
};
114
148

115
149
print_r(array_map($func, range(1, 5)));
150
+

151
+
// Or as of PHP 7.4.0:
152
+

153
+
print_r(array_map(fn($value): int => $value * 2, range(1, 5)));
154
+

116
155
?>
117
156
]]>
118
157
</programlisting>
158
+
&example.outputs;
119
159
<screen>
120
160
<![CDATA[
121
161
Array
...
...
@@ -136,23 +176,23 @@ Array
136
176
<programlisting role="php">
137
177
<![CDATA[
138
178
<?php
139
-
function show_Spanish($n, $m)
179
+
function show_Spanish(int $n, string $m): string
140
180
{
141
-
return("The number $n is called $m in Spanish");
181
+
return "The number {$n} is called {$m} in Spanish";
142
182
}
143
183

144
-
function map_Spanish($n, $m)
184
+
function map_Spanish(int $n, string $m): array
145
185
{
146
-
return(array($n => $m));
186
+
return [$n => $m];
147
187
}
148
188

149
-
$a = array(1, 2, 3, 4, 5);
150
-
$b = array("uno", "dos", "tres", "cuatro", "cinco");
189
+
$a = [1, 2, 3, 4, 5];
190
+
$b = ['uno', 'dos', 'tres', 'cuatro', 'cinco'];
151
191

152
-
$c = array_map("show_Spanish", $a, $b);
192
+
$c = array_map('show_Spanish', $a, $b);
153
193
print_r($c);
154
194

155
-
$d = array_map("map_Spanish", $a , $b);
195
+
$d = array_map('map_Spanish', $a , $b);
156
196
print_r($d);
157
197
?>
158
198
]]>
...
...
@@ -217,13 +257,13 @@ Array
217
257
</para>
218
258
<para>
219
259
<example>
220
-
<title>Creating an array of arrays</title>
260
+
<title>Performing a zip operation of arrays</title>
221
261
<programlisting role="php">
222
262
<![CDATA[
223
263
<?php
224
-
$a = array(1, 2, 3, 4, 5);
225
-
$b = array("one", "two", "three", "four", "five");
226
-
$c = array("uno", "dos", "tres", "cuatro", "cinco");
264
+
$a = [1, 2, 3, 4, 5];
265
+
$b = ['one', 'two', 'three', 'four', 'five'];
266
+
$c = ['uno', 'dos', 'tres', 'cuatro', 'cinco'];
227
267

228
268
$d = array_map(null, $a, $b, $c);
229
269
print_r($d);
...
...
@@ -275,10 +315,35 @@ Array
275
315
</screen>
276
316
</example>
277
317
</para>
318
+
278
319
<para>
279
-
The returned array will preserve the keys of the array argument if and only
280
-
if exactly one array is passed. If more than one array is passed, the
281
-
returned array will have sequential integer keys.
320
+
<example>
321
+
<title>
322
+
&null; <parameter>callback</parameter> with only
323
+
<parameter>array</parameter>
324
+
</title>
325
+
<programlisting role="php">
326
+
<![CDATA[
327
+
<?php
328
+
$array = [1, 2, 3];
329
+
var_dump(array_map(null, $array));
330
+
?>
331
+
]]>
332
+
</programlisting>
333
+
&example.outputs;
334
+
<screen>
335
+
<![CDATA[
336
+
array(3) {
337
+
[0]=>
338
+
int(1)
339
+
[1]=>
340
+
int(2)
341
+
[2]=>
342
+
int(3)
343
+
}
344
+
]]>
345
+
</screen>
346
+
</example>
282
347
</para>
283
348
<para>
284
349
<example>
...
...
@@ -286,15 +351,15 @@ Array
286
351
<programlisting role="php">
287
352
<![CDATA[
288
353
<?php
289
-
$arr = array("stringkey" => "value");
354
+
$arr = ['stringkey' => 'value'];
290
355
function cb1($a) {
291
-
return array ($a);
356
+
return [$a];
292
357
}
293
358
function cb2($a, $b) {
294
-
return array ($a, $b);
359
+
return [$a, $b];
295
360
}
296
-
var_dump(array_map("cb1", $arr));
297
-
var_dump(array_map("cb2", $arr, $arr));
361
+
var_dump(array_map('cb1', $arr));
362
+
var_dump(array_map('cb2', $arr, $arr));
298
363
var_dump(array_map(null, $arr));
299
364
var_dump(array_map(null, $arr, $arr));
300
365
?>
...
...
@@ -332,6 +397,44 @@ array(1) {
332
397
string(5) "value"
333
398
}
334
399
}
400
+
]]>
401
+
</screen>
402
+
</example>
403
+
<example>
404
+
<title><function>array_map</function> - associative arrays</title>
405
+
<para>
406
+
While <function>array_map</function> does not directly support
407
+
using the array key as an input, that may be simulated using <function>array_keys</function>.
408
+
</para>
409
+
<programlisting role="php">
410
+
<![CDATA[
411
+
<?php
412
+
$arr = [
413
+
'v1' => 'First release',
414
+
'v2' => 'Second release',
415
+
'v3' => 'Third release',
416
+
];
417
+

418
+
// Note: Before 7.4.0, use the longer syntax for anonymous functions instead.
419
+
$callback = fn(string $k, string $v): string => "$k was the $v";
420
+

421
+
$result = array_map($callback, array_keys($arr), array_values($arr));
422
+

423
+
var_dump($result);
424
+
?>
425
+
]]>
426
+
</programlisting>
427
+
&example.outputs;
428
+
<screen>
429
+
<![CDATA[
430
+
array(3) {
431
+
[0]=>
432
+
string(24) "v1 was the First release"
433
+
[1]=>
434
+
string(25) "v2 was the Second release"
435
+
[2]=>
436
+
string(24) "v3 was the Third release"
437
+
}
335
438
]]>
336
439
</screen>
337
440
</example>
...
...
@@ -345,12 +448,10 @@ array(1) {
345
448
<member><function>array_filter</function></member>
346
449
<member><function>array_reduce</function></member>
347
450
<member><function>array_walk</function></member>
348
-
<member>&seealso.callback;</member>
349
451
</simplelist>
350
452
</para>
351
453
</refsect1>
352
454
</refentry>
353
-

354
455
<!-- Keep this comment at the end of the file
355
456
Local variables:
356
457
mode: sgml
357
458



Translation status