<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297028 $ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.array-map">
 <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>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>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>callback</parameter></term>
     <listitem>
      <para>
       Callback function to run for each element in each array.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>arr1</parameter></term>
     <listitem>
      <para>
       An array to run through the <parameter>callback</parameter> function.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>array</parameter></term>
     <listitem>
      <para>
       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 all the elements of <parameter>arr1</parameter>
   after applying the <parameter>callback</parameter> function to each one.
  </para>
 </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 = 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>
   <example>
    <title><function>array_map</function> using a lambda function (as of PHP 5.3.0)</title>
    <programlisting role="php">
<![CDATA[
<?php
$func = function($value) {
    return $value * 2;
};

print_r(array_map($func, range(1, 5)));
?>
]]>
    </programlisting>
    <screen>
<![CDATA[
Array
(
    [0] => 2
    [1] => 4
    [2] => 6
    [3] => 8
    [4] => 10
)
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <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>
    &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, 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.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>
   If the array argument contains string keys then the returned array
   will contain string keys if and only if exactly one array is passed. If 
   more than one argument is passed then the returned array always has 
   integer keys.
  </para>
  <para>
   <example>
    <title><function>array_map</function> - with string keys</title>
    <programlisting role="php">
<![CDATA[
<?php
$arr = array("stringkey" => "value");
function cb1($a) {
    return array ($a);
}
function cb2($a, $b) {
    return array ($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>
  </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>
    <member><function>create_function</function></member>
   </simplelist>
   &seealso.callback;
  </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
-->