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,19 +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
18
<function>array_map</function> returns an &array; containing
19
19
the results of applying the <parameter>callback</parameter>
20
-
to the corresponding index of <parameter>array1</parameter>
21
-
(and <parameter>...</parameter> if more arrays are provided)
20
+
to the corresponding value of <parameter>array</parameter>
21
+
(and <parameter>arrays</parameter> if more arrays are provided)
22
22
used as arguments for the callback.
23
23
The number of parameters that the <parameter>callback</parameter>
24
24
function accepts should match the number of arrays
25
-
passed to <function>array_map</function>.
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.
26
28
</para>
27
29
</refsect1>
28
30

...
...
@@ -38,14 +40,15 @@
38
40
</para>
39
41
<para>
40
42
&null; can be passed as a value to <parameter>callback</parameter>
41
-
to perform a zip operation on multiple arrays.
42
-
If only <parameter>array1</parameter> is provided,
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,
43
46
<methodname>array_map</methodname> will return the input array.
44
47
</para>
45
48
</listitem>
46
49
</varlistentry>
47
50
<varlistentry>
48
-
<term><parameter>array1</parameter></term>
51
+
<term><parameter>array</parameter></term>
49
52
<listitem>
50
53
<para>
51
54
An array to run through the <parameter>callback</parameter> function.
...
...
@@ -53,7 +56,7 @@
53
56
</listitem>
54
57
</varlistentry>
55
58
<varlistentry>
56
-
<term><parameter>...</parameter></term>
59
+
<term><parameter>arrays</parameter></term>
57
60
<listitem>
58
61
<para>
59
62
Supplementary variable list of array arguments to run through the
...
...
@@ -69,8 +72,8 @@
69
72
&reftitle.returnvalues;
70
73
<para>
71
74
Returns an array containing the results of applying the <parameter>callback</parameter>
72
-
function to the corresponding index of <parameter>array1</parameter>
73
-
(and <parameter>...</parameter> if more arrays are provided)
75
+
function to the corresponding value of <parameter>array</parameter>
76
+
(and <parameter>arrays</parameter> if more arrays are provided)
74
77
used as arguments for the callback.
75
78
</para>
76
79
<para>
...
...
@@ -80,6 +83,23 @@
80
83
</para>
81
84
</refsect1>
82
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
+

83
103
<refsect1 role="examples">
84
104
&reftitle.examples;
85
105
<para>
...
...
@@ -118,18 +138,24 @@ Array
118
138
</para>
119
139
<para>
120
140
<example>
121
-
<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>
122
142
<programlisting role="php">
123
143
<![CDATA[
124
144
<?php
125
-
$func = function($value) {
145
+
$func = function(int $value): int {
126
146
return $value * 2;
127
147
};
128
148

129
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
+

130
155
?>
131
156
]]>
132
157
</programlisting>
158
+
&example.outputs;
133
159
<screen>
134
160
<![CDATA[
135
161
Array
...
...
@@ -150,12 +176,12 @@ Array
150
176
<programlisting role="php">
151
177
<![CDATA[
152
178
<?php
153
-
function show_Spanish($n, $m)
179
+
function show_Spanish(int $n, string $m): string
154
180
{
155
181
return "The number {$n} is called {$m} in Spanish";
156
182
}
157
183

158
-
function map_Spanish($n, $m)
184
+
function map_Spanish(int $n, string $m): array
159
185
{
160
186
return [$n => $m];
161
187
}
...
...
@@ -294,7 +320,7 @@ Array
294
320
<example>
295
321
<title>
296
322
&null; <parameter>callback</parameter> with only
297
-
<parameter>array1</parameter>
323
+
<parameter>array</parameter>
298
324
</title>
299
325
<programlisting role="php">
300
326
<![CDATA[
...
...
@@ -371,6 +397,44 @@ array(1) {
371
397
string(5) "value"
372
398
}
373
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
+
}
374
438
]]>
375
439
</screen>
376
440
</example>
...
...
@@ -388,7 +452,6 @@ array(1) {
388
452
</para>
389
453
</refsect1>
390
454
</refentry>
391
-

392
455
<!-- Keep this comment at the end of the file
393
456
Local variables:
394
457
mode: sgml
395
458



Translation status