array-multisort.xml

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

<refentry xml:id="function.array-multisort" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>array_multisort</refname>
  <refpurpose>Trie les tableaux multidimensionnels</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>array_multisort</methodname>
   <methodparam><type>array</type><parameter role="reference">array1</parameter></methodparam>
   <methodparam choice="opt"><type>mixed</type><parameter>array1_sort_order</parameter><initializer>SORT_ASC</initializer></methodparam>
   <methodparam choice="opt"><type>mixed</type><parameter>array1_sort_flags</parameter><initializer>SORT_REGULAR</initializer></methodparam>
   <methodparam rep="repeat"><type>mixed</type><parameter>rest</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>array_multisort</function> sert à trier simultanément
   plusieurs tableaux, ou bien à trier un tableau multidimensionnel,
   suivant l'une ou l'autre de ses dimensions.
  </para>
  <para>
   Les clés associatives (&string;) seront maintenues, mais
   les clés numériques seront réindexées.
  </para>
  &note.sort-unstable;
  &note.reset-index;
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>array1</parameter></term>
     <listitem>
      <para>
       Un &array; à trier.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>array1_sort_order</parameter></term>
     <listitem>
      <para>
       L'ordre utilisé pour trier le précédent argument
       <type>array</type>. Soit la constante <constant>SORT_ASC</constant>
       pour trier de façon croissant, soit la constante
       <constant>SORT_DESC</constant> pour trier de façon décroissant.
      </para>
      <para>
       Cet argument peut être associé avec le paramètre
       <parameter>array1_sort_flags</parameter> ou simplement omis,
       auquel cas, la constante <constant>SORT_ASC</constant> sera utilisée.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>array1_sort_flags</parameter></term>
     <listitem>
      <para>
       Options de tri du précédent argument <type>array</type> :
      </para>
      <para>
       Type d'options de tri :
       <itemizedlist>
        <listitem>
         <simpara><constant>SORT_REGULAR</constant> - compare les éléments normalement (pas de changement de type)</simpara>
        </listitem>
        <listitem>
         <simpara><constant>SORT_NUMERIC</constant> - compare les éléments numériquement</simpara>
        </listitem>
        <listitem>
         <simpara><constant>SORT_STRING</constant> - compare les éléments sous forme de chaînes de caractères</simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>SORT_LOCALE_STRING</constant> - compare les éléments sous forme de chaînes de caractères,
          en se basant sur la locale courante. La fonction utilise les locales, et elles peuvent être modifiées
          en utilisant la fonction <function>setlocale</function>
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>SORT_NATURAL</constant> - compre les éléments sous forme de chaînes de caractères, en utilisant
          le "tri naturel", comme le fait la fonction <function>natsort</function>
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>SORT_FLAG_CASE</constant> - peut être combiné (avec le mot clé OR) avec
          <constant>SORT_STRING</constant> ou
          <constant>SORT_NATURAL</constant> pour trier les chaînes sans tenir compte de la casse
         </simpara>
        </listitem>
       </itemizedlist>
      </para>
      <para>
       Cet argument peut être associé avec le paramètre <parameter>array1_sort_order</parameter>
       ou simplement omis, auquel cas, la constante <constant>SORT_REGULAR</constant> sera utilisée.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>rest</parameter></term>
     <listitem>
      <para>
       Plus d'arguments, optionnellement suivis par des façons de trier et des
       drapeaux. Seuls les éléments équivalents dans les tableaux précédents
       sont comparés. En d'autres termes, le tri est lexicographique.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Trier plusieurs tableaux</title>
    <programlisting role="php">
<![CDATA[
<?php
$ar1 = array(10, 100, 100, 0);
$ar2 = array(1, 3, 2, 4);
array_multisort($ar1, $ar2);

var_dump($ar1);
var_dump($ar2);
?>
]]>
    </programlisting>
    <para>
     Dans cet exemple, après le tri, le premier
     tableau contient 0, 10, 100, 100. Le deuxième tableau
     contient 4, 1, 2, 3. Les entrées du second tableau
     correspondant aux valeurs jumelles du premier
     tableau (100 et 100), sont aussi triées.
    </para>
    <screen>
<![CDATA[
array(4) {
  [0]=> int(0)
  [1]=> int(10)
  [2]=> int(100)
  [3]=> int(100)
}
array(4) {
  [0]=> int(4)
  [1]=> int(1)
  [2]=> int(2)
  [3]=> int(3)
}
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Trier un tableau multidimensionnel</title>
    <programlisting role="php">
<![CDATA[
<?php
$ar = array(
       array("10", 11, 100, 100, "a"),
       array(   1,  2, "2",   3,   1)
      );
array_multisort($ar[0], SORT_ASC, SORT_STRING,
                $ar[1], SORT_NUMERIC, SORT_DESC);
var_dump($ar);
?>
]]>
    </programlisting>
    <para>
     Dans cet exemple, après le tri, le premier tableau contient
     "10", 100, 100, 11, "a" (tri alphabétique, ordre croissant); Le
     deuxième tableau contient 1, 3, "2", 2, 1 (tri
     numérique, ordre décroissant).
    </para>
    <screen>
<![CDATA[
array(2) {
  [0]=> array(5) {
    [0]=> string(2) "10"
    [1]=> int(100)
    [2]=> int(100)
    [3]=> int(11)
    [4]=> string(1) "a"
  }
  [1]=> array(5) {
    [0]=> int(1)
    [1]=> int(3)
    [2]=> string(1) "2"
    [3]=> int(2)
    [4]=> int(1)
  }
}
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Classer les résultats d'une base de données</title>
    <para>
     Dans cet exemple, chaque élément du tableau <varname>data</varname>
     représente une ligne de la table. Ce type de données est typique d'un
     enregistrement de base de données.
    </para>
    <para>
     Exemple de données :
    </para>
    <screen>
<![CDATA[
volume | edition
-------+--------
    67 |       2
    86 |       1
    85 |       6
    98 |       2
    86 |       6
    67 |       7
]]>
    </screen>
    <para>
     Les données sont sous forme de tableau, appelé <varname>data</varname>. 
     Cela est généralement le résultat, par exemple, de la fonction 
     <function>mysqli_fetch_assoc</function>.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$data[] = array('volume' => 67, 'edition' => 2);
$data[] = array('volume' => 86, 'edition' => 1);
$data[] = array('volume' => 85, 'edition' => 6);
$data[] = array('volume' => 98, 'edition' => 2);
$data[] = array('volume' => 86, 'edition' => 6);
$data[] = array('volume' => 67, 'edition' => 7);
?>
]]>
    </programlisting>
    <para>
     Dans cet exemple, nous allons trier la colonne
     <varname>volume</varname> par ordre décroissant, et
     la colonne <varname>edition</varname> par ordre croissant.
    </para>
    <para>
     Nous avons un tableau de lignes, mais 
     <function>array_multisort</function> nécessite un tableau de colonnes, 
     donc nous utilisons le code suivant pour obtenir les colonnes et 
     ainsi effectuer le tri.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// Obtient une liste de colonnes
foreach ($data as $key => $row) {
    $volume[$key]  = $row['volume'];
    $edition[$key] = $row['edition'];
}

// vous pouvez utiliser array_column() au lieu du code ci-dessus
$volume  = array_column($data, 'volume');
$edition = array_column($data, 'edition');

// Trie les données par volume décroissant, edition croissant
// Ajoute $data en tant que dernier paramètre, pour trier par la clé commune
array_multisort($volume, SORT_DESC, $edition, SORT_ASC, $data);
?>
]]>
    </programlisting>
    <para>
     Le jeu d'enregistrement est maintenant trié et ressemble à cela :
    </para>
    <screen>
<![CDATA[
volume | edition
-------+--------
    98 |       2
    86 |       1
    86 |       6
    85 |       6
    67 |       2
    67 |       7
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Tri non sensible à la casse</title>
    <para>
     <constant>SORT_STRING</constant> et
     <constant>SORT_REGULAR</constant> sont sensibles à la casse, les chaînes
     de caractères commençant avec une lettre en majuscule viendront avant
     les chaînes de caractères commençant par une lettre en minuscule.
    </para>
    <para>
     Pour effectuer un tri insensible à la casse, effectuez le tri
     sur une copie minuscule des colonnes du tableau original.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$array = array('Alpha', 'atomic', 'Beta', 'bank');
$array_lowercase = array_map('strtolower', $array);

array_multisort($array_lowercase, SORT_ASC, SORT_STRING, $array);

print_r($array);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Array
(
    [0] => Alpha
    [1] => atomic
    [2] => bank
    [3] => Beta
)
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>usort</function></member>
    <member>&seealso.array.sorting;</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
-->