<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.12 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.62 -->
  <refentry id="function.array-map">
   <refnamediv>
    <refname>array_map</refname>
    <refpurpose>
     Applies the callback to the elements of the given arrays
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <methodsynopsis>
     <type>array</type><methodname>array_map</methodname>
     <methodparam><type>callback</type><parameter>callback</parameter></methodparam>
     <methodparam><type>array</type><parameter>arr1</parameter></methodparam>
     <methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam>
    </methodsynopsis>
    <para>
     <function>array_map</function> returns an array containing all
     the elements of <parameter>arr1</parameter> after applying the
     <parameter>callback</parameter> function to each one.
     The number of parameters that the <parameter>callback</parameter>
     function accepts
     should match the number of arrays
     passed to the <function>array_map</function>
    </para>
    <para>
     <example>
      <title><function>array_map</function> example</title>
      <programlisting role="php">
<![CDATA[
<?php
function cube($n) 
{
    return($n * $n * $n);
}

$a = array(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 more arrays</title>
      <programlisting role="php">
<![CDATA[
<?php
function show_Spanish($n, $m) 
{
    return("The number $n is called $m in Spanish");
}

function map_Spanish($n, $m) 
{
    return(array($n => $m));
}

$a = array(1, 2, 3, 4, 5);
$b = array("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>
      <para>
       This results:
      </para>
      <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, the shortest one will be extended
     with empty elements.
    </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>Creating an array of arrays</title>
      <programlisting role="php">
<![CDATA[
<?php
$a = array(1, 2, 3, 4, 5);
$b = array("one", "two", "three", "four", "five");
$c = array("uno", "dos", "tres", "cuatro", "cinco");

$d = array_map(null, $a, $b, $c);
print_r($d);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     The printout of the program above will be:
    </para>
    <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>
    <para>
     See also <function>array_filter</function>, 
     <function>array_reduce</function>, and
     <function>array_walk</function>.
    </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:"../../../../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
-->