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,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

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

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

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

130
154
?>
131
155
]]>
132
156
</programlisting>
...
...
@@ -150,12 +174,12 @@ Array
150
174
<programlisting role="php">
151
175
<![CDATA[
152
176
<?php
153
-
function show_Spanish($n, $m)
177
+
function show_Spanish(int $n, string $m): string
154
178
{
155
179
return "The number {$n} is called {$m} in Spanish";
156
180
}
157
181

158
-
function map_Spanish($n, $m)
182
+
function map_Spanish(int $n, string $m): array
159
183
{
160
184
return [$n => $m];
161
185
}
...
...
@@ -294,7 +318,7 @@ Array
294
318
<example>
295
319
<title>
296
320
&null; <parameter>callback</parameter> with only
297
-
<parameter>array1</parameter>
321
+
<parameter>array</parameter>
298
322
</title>
299
323
<programlisting role="php">
300
324
<![CDATA[
...
...
@@ -374,6 +398,44 @@ array(1) {
374
398
]]>
375
399
</screen>
376
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>
377
439
</para>
378
440
</refsect1>
379
441

...
...
@@ -388,7 +450,6 @@ array(1) {
388
450
</para>
389
451
</refsect1>
390
452
</refentry>
391
-

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