reference/array/functions/array-map.xml
e8c83816e0ca7a4136a5991b2227ddf00fa9adc6
...
...
@@ -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,18 @@
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.
44
+
If only <parameter>array</parameter> is provided,
45
+
<methodname>array_map</methodname> will return the input array.
37
46
</para>
38
47
</listitem>
39
48
</varlistentry>
40
49
<varlistentry>
41
-
<term><parameter>array1</parameter></term>
50
+
<term><parameter>array</parameter></term>
42
51
<listitem>
43
52
<para>
44
53
An array to run through the <parameter>callback</parameter> function.
...
...
@@ -46,10 +55,10 @@
46
55
</listitem>
47
56
</varlistentry>
48
57
<varlistentry>
49
-
<term><parameter>...</parameter></term>
58
+
<term><parameter>arrays</parameter></term>
50
59
<listitem>
51
60
<para>
52
-
Variable list of array arguments to run through the
61
+
Supplementary variable list of array arguments to run through the
53
62
<parameter>callback</parameter> function.
54
63
</para>
55
64
</listitem>
...
...
@@ -61,11 +70,35 @@
61
70
<refsect1 role="returnvalues">
62
71
&reftitle.returnvalues;
63
72
<para>
64
-
Returns an array containing all the elements of <parameter>array1</parameter>
65
-
after applying the <parameter>callback</parameter> function to each one.
73
+
Returns an array containing the results of applying the <parameter>callback</parameter>
74
+
function to the corresponding value of <parameter>array</parameter>
75
+
(and <parameter>arrays</parameter> if more arrays are provided)
76
+
used as arguments for the callback.
77
+
</para>
78
+
<para>
79
+
The returned array will preserve the keys of the array argument if and only
80
+
if exactly one array is passed. If more than one array is passed, the
81
+
returned array will have sequential integer keys.
66
82
</para>
67
83
</refsect1>
68
84

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

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

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

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

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

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

116
154
?>
117
155
]]>
118
156
</programlisting>
...
...
@@ -136,23 +174,23 @@ Array
136
174
<programlisting role="php">
137
175
<![CDATA[
138
176
<?php
139
-
function show_Spanish($n, $m)
177
+
function show_Spanish(int $n, string $m): string
140
178
{
141
-
return("The number $n is called $m in Spanish");
179
+
return "The number {$n} is called {$m} in Spanish";
142
180
}
143
181

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

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

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

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

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

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

419
+
$result = array_map($callback, array_keys($arr), array_values($arr));
420
+

421
+
var_dump($result);
422
+
?>
423
+
]]>
424
+
</programlisting>
425
+
&example.outputs;
426
+
<screen>
427
+
<![CDATA[
428
+
array(3) {
429
+
[0]=>
430
+
string(24) "v1 was the First release"
431
+
[1]=>
432
+
string(25) "v2 was the Second release"
433
+
[2]=>
434
+
string(24) "v3 was the Third release"
435
+
}
436
+
]]>
437
+
</screen>
438
+
</example>
338
439
</para>
339
440
</refsect1>
340
441

...
...
@@ -345,12 +446,10 @@ array(1) {
345
446
<member><function>array_filter</function></member>
346
447
<member><function>array_reduce</function></member>
347
448
<member><function>array_walk</function></member>
348
-
<member>&seealso.callback;</member>
349
449
</simplelist>
350
450
</para>
351
451
</refsect1>
352
452
</refentry>
353
-

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