doc-fr/reference/array/functions/array-map.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 108ea73be559f6752a461149fffa9b294545359f Maintainer: yannick Status: ready -->
<!-- CREDITS: DavidA. -->

<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.array-map">
 <refnamediv>
  <refname>array_map</refname>
  <refpurpose>Applique une fonction sur les éléments d'un tableau</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>array_map</methodname>
   <methodparam><type>callable</type><parameter>callback</parameter></methodparam>
   <methodparam><type>array</type><parameter>array1</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>...</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>array_map</function> retourne un &array; contenant
   les résultats de l'application de la fonction de rappel
   <parameter>callback</parameter> à l'index correspondant de
   <parameter>array1</parameter> (et <parameter>...</parameter> si plus de
   tableaux sont fourni) utilisé en tant qu'arguments pour la fonction de rappel.
   Le nombre de paramètres que la fonction de rappel <parameter>callback</parameter>
   accepte devrait correspondre au nombre de tableaux passé à
   <function>array_map</function>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>callback</parameter></term>
     <listitem>
      <para>
       La fonction de rappel à exécuter pour chaque élément de chaque
       tableau.
      </para>
      <para>
       &null; peut être passé comme valeur à <parameter>callback</parameter>
       pour executer une opération zip sur plusieurs tableaux.
       Si seulement <parameter>array1</parameter> est fourni,
       <methodname>array_map</methodname> retournera le tableau d'entré.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>array1</parameter></term>
     <listitem>
      <para>
       Un tableau à exécuter via la fonction de rappel <parameter>callback</parameter>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>...</parameter></term>
     <listitem>
      <para>
       Liste variable d'arguments tableaux supplémentaires à exécuter via
       la fonction de rappel <parameter>callback</parameter>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne un tableau contenant les résultats de l'application de la fonction
   de rappel <parameter>callback</parameter> à l'index correspondant de
   <parameter>array1</parameter> (et <parameter>...</parameter> si plus de
   tableaux sont fourni) utilisé en tant qu'arguments pour la fonction de rappel.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>array_map</function></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>
     Le contenu de la variable <varname>$b</varname> sera :
    </para>
    <screen>
<![CDATA[
Array
(
    [0] => 1
    [1] => 8
    [2] => 27
    [3] => 64
    [4] => 125
)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><function>array_map</function> : utilisation d'une fonction 
     quelconque (depuis 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>
  <para>
   <example>
    <title><function>array_map</function> : utilisation de plusieurs tableaux</title>
    <programlisting role="php">
<![CDATA[
<?php
function show_Spanish($n, $m)
{
    return "Le nombre {$n} se dit {$m} en Espagnol";
}

function map_Spanish($n, $m)
{
    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[
// Contenu de $c
Array
(
    [0] => Le nombre 1 se dit uno en Espagnol
    [1] => Le nombre 2 se dit dos en Espagnol
    [2] => Le nombre 3 se dit tres en Espagnol
    [3] => Le nombre 4 se dit cuatro en Espagnol
    [4] => Le nombre 5 se dit cinco en Espagnol
)

// Contenu de $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>
   Généralement, lors de l'utilisation de plusieurs tableaux, ils doivent
   être d'égale longueur, car la fonction de rappel est appliquée de manière
   similaire à tous les tableaux. Si les tableaux sont de tailles inégales,
   les plus petits seront complétés avec des éléments vides pour atteindre
   la taille du plus grand.
  </para>
  <para>
   Une utilisation intéressante de cette fonction est la construction
   de tableaux de tableaux, facilement réalisée en passant la valeur
   &null; comme nom de fonction de rappel.
  </para>
  <para>
   <example>
    <title>Exécution d'une opération zip de tableaux</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>
   Le tableau retourné conservera les clés du tableau passé en argument, 
   si et seulement si, un seul tableau est passé. Si plusieurs tableaux 
   sont passés comme argument, le tableau retourné aura des clés sous la 
   forme d'entier.
  </para>
  
  <para>
   <example>
    <title>
     &null; <parameter>callback</parameter> avec seulement
     <parameter>array1</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> - avec des clés sous la forme de &string;
    </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>
  </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>&seealso.callback;</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
-->