<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.array-map" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>array_map</refname>
  <refpurpose>Applies the callback to the elements of the given arrays</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>array_map</methodname>
   <methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>
   <methodparam><type>array</type><parameter>array</parameter></methodparam>
   <methodparam rep="repeat"><type>array</type><parameter>arrays</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>array_map</function> returns an &array; containing
   the results of applying the <parameter>callback</parameter>
   to the corresponding value of <parameter>array</parameter>
   (and <parameter>arrays</parameter> if more arrays are provided)
   used as arguments for the callback.
   The number of parameters that the <parameter>callback</parameter>
   function accepts should match the number of arrays
   passed to <function>array_map</function>. Excess
   input arrays are ignored. An <classname>ArgumentCountError</classname>
   is thrown if an insufficient number of arguments is provided.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>callback</parameter></term>
     <listitem>
      <para>
       A <type>callable</type> to run for each element in each array.
      </para>
      <para>
       &null; can be passed as a value to <parameter>callback</parameter>
       to perform a zip operation on multiple arrays and return an array
       whose elements are each an array holding the elements of the input arrays of the same index (see example below).
       If only <parameter>array</parameter> is provided,
       <methodname>array_map</methodname> will return the input array.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>array</parameter></term>
     <listitem>
      <para>
       An array to run through the <parameter>callback</parameter> function.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>arrays</parameter></term>
     <listitem>
      <para>
       Supplementary variable list of array arguments to run through the
       <parameter>callback</parameter> function.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an array containing the results of applying the <parameter>callback</parameter>
   function to the corresponding value of <parameter>array</parameter>
   (and <parameter>arrays</parameter> if more arrays are provided)
   used as arguments for the callback.
  </para>
  <para>
   The returned array will preserve the keys of the array argument if and only
   if exactly one array is passed. If more than one array is passed, the
   returned array will have sequential integer keys.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     &array.changelog.by-ref;
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>array_map</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
function cube($n)
{
    return ($n * $n * $n);
}

$a = [1, 2, 3, 4, 5];
$b = array_map('cube', $a);
print_r($b);
?>
]]>
    </programlisting>
    <para>
     This makes <varname>$b</varname> have:
    </para>
    <screen>
<![CDATA[
Array
(
    [0] => 1
    [1] => 8
    [2] => 27
    [3] => 64
    [4] => 125
)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><function>array_map</function> using a lambda function</title>
    <programlisting role="php">
<![CDATA[
<?php
$func = function(int $value): int {
    return $value * 2;
};

print_r(array_map($func, range(1, 5)));

// Or as of PHP 7.4.0:

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

?>
]]>
    </programlisting>
    <screen>
<![CDATA[
Array
(
    [0] => 2
    [1] => 4
    [2] => 6
    [3] => 8
    [4] => 10
)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><function>array_map</function> - using more arrays</title>
    <programlisting role="php">
<![CDATA[
<?php
function show_Spanish(int $n, string $m): string
{
    return "The number {$n} is called {$m} in Spanish";
}

function map_Spanish(int $n, string $m): array
{
    return [$n => $m];
}

$a = [1, 2, 3, 4, 5];
$b = ['uno', 'dos', 'tres', 'cuatro', 'cinco'];

$c = array_map('show_Spanish', $a, $b);
print_r($c);

$d = array_map('map_Spanish', $a , $b);
print_r($d);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
// printout of $c
Array
(
    [0] => The number 1 is called uno in Spanish
    [1] => The number 2 is called dos in Spanish
    [2] => The number 3 is called tres in Spanish
    [3] => The number 4 is called cuatro in Spanish
    [4] => The number 5 is called cinco in Spanish
)

// printout of $d
Array
(
    [0] => Array
        (
            [1] => uno
        )

    [1] => Array
        (
            [2] => dos
        )

    [2] => Array
        (
            [3] => tres
        )

    [3] => Array
        (
            [4] => cuatro
        )

    [4] => Array
        (
            [5] => cinco
        )

)
]]>
    </screen>
   </example>
  </para>
  <para>
   Usually when using two or more arrays, they should be of equal length
   because the callback function is applied in parallel to the corresponding
   elements.
   If the arrays are of unequal length, shorter ones will be extended with empty
   elements to match the length of the longest.
  </para>
  <para>
   An interesting use of this function is to construct an array of arrays,
   which can be easily performed by using &null;
   as the name of the callback function
  </para>
  <para>
   <example>
    <title>Performing a zip operation of arrays</title>
    <programlisting role="php">
<![CDATA[
<?php
$a = [1, 2, 3, 4, 5];
$b = ['one', 'two', 'three', 'four', 'five'];
$c = ['uno', 'dos', 'tres', 'cuatro', 'cinco'];

$d = array_map(null, $a, $b, $c);
print_r($d);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Array
(
    [0] => Array
        (
            [0] => 1
            [1] => one
            [2] => uno
        )

    [1] => Array
        (
            [0] => 2
            [1] => two
            [2] => dos
        )

    [2] => Array
        (
            [0] => 3
            [1] => three
            [2] => tres
        )

    [3] => Array
        (
            [0] => 4
            [1] => four
            [2] => cuatro
        )

    [4] => Array
        (
            [0] => 5
            [1] => five
            [2] => cinco
        )

)
]]>
    </screen>
   </example>
  </para>
  
  <para>
   <example>
    <title>
     &null; <parameter>callback</parameter> with only
     <parameter>array</parameter>
    </title>
    <programlisting role="php">
<![CDATA[
<?php
$array = [1, 2, 3];
var_dump(array_map(null, $array));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(3) {
  [0]=>
  int(1)
  [1]=>
  int(2)
  [2]=>
  int(3)
}
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><function>array_map</function> - with string keys</title>
    <programlisting role="php">
<![CDATA[
<?php
$arr = ['stringkey' => 'value'];
function cb1($a) {
    return [$a];
}
function cb2($a, $b) {
    return [$a, $b];
}
var_dump(array_map('cb1', $arr));
var_dump(array_map('cb2', $arr, $arr));
var_dump(array_map(null,  $arr));
var_dump(array_map(null, $arr, $arr));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(1) {
  ["stringkey"]=>
  array(1) {
    [0]=>
    string(5) "value"
  }
}
array(1) {
  [0]=>
  array(2) {
    [0]=>
    string(5) "value"
    [1]=>
    string(5) "value"
  }
}
array(1) {
  ["stringkey"]=>
  string(5) "value"
}
array(1) {
  [0]=>
  array(2) {
    [0]=>
    string(5) "value"
    [1]=>
    string(5) "value"
  }
}
]]>
    </screen>
   </example>
   <example>
    <title><function>array_map</function> - associative arrays</title>
    <para>
     While <function>array_map</function> does not directly support
     using the array key as an input, that may be simulated using <function>array_keys</function>.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$arr = [
    'v1' => 'First release',
    'v2' => 'Second release',
    'v3' => 'Third release',
];

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

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

var_dump($result);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(3) {
  [0]=>
  string(24) "v1 was the First release"
  [1]=>
  string(25) "v2 was the Second release"
  [2]=>
  string(24) "v3 was the Third release"
}
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>array_filter</function></member>
    <member><function>array_reduce</function></member>
    <member><function>array_walk</function></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->