array-multisort.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 6a6f43d1c490a57b452656db285de6d136055ed2 Maintainer: gerdtsteltner Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: 6a6f43d1c490a57b452656db285de6d136055ed2 Reviewer: samesch -->
<refentry xml:id="function.array-multisort" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>array_multisort</refname>
  <refpurpose>Sortiert mehrere oder multidimensionale Arrays</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> kann verwendet werden, um entweder
   mehrere Arrays auf einmal zu sortieren, oder ein multidimensionales Array
   nach einer oder mehreren Dimensionen.
  </para>
  <para>
   Assoziative (<type>&string;</type>-) Schlüssel werden beibehalten,
   während numerische Schlüssel neu indexiert werden.
  </para>
  &note.sort-unstable;
  &note.reset-index;
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>array1</parameter></term>
     <listitem>
      <para>
       Ein zu sortierendes <type>&array;</type>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>array1_sort_order</parameter></term>
     <listitem>
      <para>
       Die Reihenfolge, die verwendet wird, um das vorangehende
       <type>Array</type>-Argument zu sortieren. Entweder
       <constant>SORT_ASC</constant>, um aufsteigend zu sortieren, oder
       <constant>SORT_DESC</constant>, um absteigend zu sortieren.
      </para>
      <para>
       Dieses Argument kann mit <parameter>array1_sort_flags</parameter>
       vertauscht werden oder ganz entfallen, wobei dann
       <constant>SORT_ASC</constant> angenommen wird.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>array1_sort_flags</parameter></term>
     <listitem>
      <para>
       Sortieroptionen für das vorangehende <type>Array</type>-Argument:
      </para>
      <para>
       Sortier-Flags:
       <itemizedlist>
        <listitem>
         <simpara>
          <constant>SORT_REGULAR</constant> - vergleiche Elemente normal
          (ändere nicht die Typen)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>SORT_NUMERIC</constant> - vergleiche Elemente numerisch
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>SORT_STRING</constant> - vergleiche Elemente als
          Zeichenketten
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>SORT_LOCALE_STRING</constant> - vergleiche Elemente als
          Zeichenketten, basierend auf dem aktuellen Gebietschema. Es
          verwendet das Gebietsschema, das unter Verwendung von
          <function>setlocale</function> geändert werden kann
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>SORT_NATURAL</constant> - vergleiche Elemente als
          Zeichenketten unter Verwendung einer "natürlichen Ordnung" wie
          <function>natsort</function>
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>SORT_FLAG_CASE</constant> - kann kombiniert werden
          (bitweises OR) mit <constant>SORT_STRING</constant> oder
          <constant>SORT_NATURAL</constant>, um Zeichenketten ohne
          Berücksichtigung der Groß- und Kleinschreibung zu sortieren
         </simpara>
        </listitem>
       </itemizedlist>
      </para>
      <para>
       Dieses Argument kann mit <parameter>array1_sort_order</parameter>
       vertauscht werden oder ganz entfallen, wobei dann
       <constant>SORT_REGULAR</constant> angenommen wird.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>rest</parameter></term>
     <listitem>
      <para>
       Weitere Arrays, optional gefolgt von Sortierreihenfolge und -Flags. Nur
       Elemente, die äquivalenten Elementen in vorherigen Arrays entsprechen,
       werden verglichen. Anders ausgedrückt erfolgt die Sortierung
       lexikographisch.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Sortieren mehrerer Arrays</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>
     In diesem Beispiel enthält das erste Array nach dem Sortieren 0, 10, 100,
     100. Das zweite Array wird 4, 1, 2, 3 enthalten. Die Einträge des zweiten
     Arrays, welche den identischen Einträgen des ersten Arrays entsprechen
     (100 und 100), werden ebenfalls sortiert.
    </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>Sortieren eines mehrdimensionalen Arrays</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>
     In diesem Beispiel wird sich das erste Array nach der Sortierung in "10",
     100, 100, 11, "a" ändern (es wurde als Zeichenketten in aufsteigender
     Reihenfolge sortiert). Das zweite wird 1, 3, "2", 2, 1 enthalten
     (sortiert als Zahlen in absteigender Reihenfolge).
    </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>Datenbankdaten sortieren</title>
    <para>
     In diesem Beispiel repräsentiert jedes Element des Arrays
     <varname>data</varname> eine Zeile einer Tabelle. Dieser Typ
     von Datensätzen ist typisch für Datenbankinhalte.
    </para>
    <para>
     Beispieldaten:
    </para>
    <screen>
<![CDATA[
Band   | Auflage
-------+--------
    67 |       2
    86 |       1
    85 |       6
    98 |       2
    86 |       6
    67 |       7
]]>
    </screen>
    <para>
     Die Daten als <varname>data</varname> genanntes Array. Dieses würde
     man üblicherweise mit einer Schleife über die Ergebnisse von
     <function>mysql_fetch_assoc</function> erhalten.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$data[] = array('Band' => 67, 'Auflage' => 2);
$data[] = array('Band' => 86, 'Auflage' => 1);
$data[] = array('Band' => 85, 'Auflage' => 6);
$data[] = array('Band' => 98, 'Auflage' => 2);
$data[] = array('Band' => 86, 'Auflage' => 6);
$data[] = array('Band' => 67, 'Auflage' => 7);
?>
]]>
    </programlisting>
    <para>
     In diesem Beispiel werden wir absteigend nach <varname>Band</varname>
     sortieren und aufsteigend nach <varname>Auflage</varname>.
    </para>
    <para>
     Wir haben ein Array von Zeilen, aber <function>array_multisort</function>
     benötigt ein Array von Spalten, also benutzen wir den Code unten, um die
     Spalten zu bekommen und dann die Sortierung durchzuführen.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// Hole eine Liste von Spalten
foreach ($data as $key => $row) {
    $band[$key]    = $row['Band'];
    $auflage[$key] = $row['Auflage'];
}

// statt des obigen Codes kann array_column() verwendet werden
$band  = array_column($data, 'Band');
$auflage = array_column($data, 'Auflage');

// Die Daten mit 'Band' absteigend, die mit 'Auflage' aufsteigend sortieren.
// Geben Sie $data als letzten Parameter an, um nach dem gemeinsamen
// Schlüssel zu sortieren.
array_multisort($band, SORT_DESC, $auflage, SORT_ASC, $data);
?>
]]>
    </programlisting>
    <para>
     Der Datensatz ist jetzt sortiert und wird wie folgt aussehen:
    </para>
    <screen>
<![CDATA[
Band | Auflage
-----+--------
  98 |       2
  86 |       1
  86 |       6
  85 |       6
  67 |       2
  67 |       7
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Groß-/Kleinschreibung nicht-beachtende Sortierung</title>
    <para>
     Sowohl <constant>SORT_STRING</constant> als auch
     <constant>SORT_REGULAR</constant> beachten die Groß-/Kleinschreibung,
     weshalb Zeichenketten, welche mit großem Buchstaben beginnen, vor
     Zeichenketten einsortiert werden, die mit kleinem Buchstaben anfangen.
    </para>
    <para>
     Um eine Suche durchzuführen, die die Groß-/Kleinschreibung nicht
     beachtet, muss man erzwingen, dass die Sortierreihenfolge von einer
     Kopie des Originalarrays in Kleinschreibung festgelegt wird.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$array = array('Alpha', 'atomar', '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] => atomar
    [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
-->