array-multisort.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 6a6f43d1c490a57b452656db285de6d136055ed2 Maintainer: hirokawa Status: ready -->
<!-- CREDITS: takagi,mumumu -->
<refentry xml:id="function.array-multisort" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>array_multisort</refname>
  <refpurpose>複数または多次元の配列をソートする</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> は、複数の配列を一度に、
   または、多次元の配列をその次元の一つでソートする際に使用可能です。
  </para>
  <para>
   連想配列のキー (<type>string</type>) は不変ですが、
   数値添字は再度振り直されます。
  </para>
  &note.sort-unstable;
  &note.reset-index;
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>array1</parameter></term>
     <listitem>
      <para>
       ソートしたい配列。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>array1_sort_order</parameter></term>
     <listitem>
      <para>
       先ほどの引数 <type>array</type> のソート順。
       <constant>SORT_ASC</constant> はアイテムを昇順にソートし、
       <constant>SORT_DESC</constant> はアイテムを降順にソートします。
      </para>
      <para>
       この引数は、<parameter>array1_sort_flags</parameter> と入れ替えることもできるし、完全に省略することもできます。
       省略した場合は <constant>SORT_ASC</constant> とみなします。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>array1_sort_flags</parameter></term>
     <listitem>
      <para>
       先ほどの引数 <type>array</type> のソート方法。
      </para>
      <para>
       これらのフラグが使えます。
       <itemizedlist>
        <listitem>
         <simpara><constant>SORT_REGULAR</constant> - アイテムを通常通り比較します (型を変更しません)。</simpara>
        </listitem>
        <listitem>
         <simpara><constant>SORT_NUMERIC</constant> - アイテムを数値として比較します。</simpara>
        </listitem>
        <listitem>
         <simpara><constant>SORT_STRING</constant> - アイテムを文字列として比較します。</simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>SORT_LOCALE_STRING</constant> -
          現在のロケールを考慮して、アイテムを文字列として比較します。利用するロケールは
          <function>setlocale</function> で変更できます。
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>SORT_NATURAL</constant> -
          <function>natsort</function> と同様の「自然順」で、アイテムを文字列として比較します。
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>SORT_FLAG_CASE</constant> -
          <constant>SORT_STRING</constant> や
          <constant>SORT_NATURAL</constant> と (ビット OR で) 組み合わせて、
          大文字小文字を区別しない文字列のソートを指定します。
         </simpara>
        </listitem>
       </itemizedlist>
      </para>
      <para>
       この引数は、<parameter>array1_sort_order</parameter> と入れ替えることもできるし、完全に省略することもできます。
       省略した場合は <constant>SORT_REGULAR</constant> とみなします。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>rest</parameter></term>
     <listitem>
      <para>
       追加の配列。オプションで並び順やフラグが続きます。
       前の配列の比較結果が等しい要素に対応する要素群だけを比較します。
       要するに、辞書的 (lexicographical) なソートを行うということです。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>複数の配列をソートする</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>
     この例では、ソートの後で、最初の配列は、0, 10, 100, 100 となります。
     2番目の配列は、4, 1, 2, 3 を有します。最初の配列で等しい要素 (100 および
     100) に対応している二番目の配列のエントリは、
     同じ順にソートされます。
    </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>多次元の配列をソートする</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>
     この例では、ソートされた後、最初の配列は "10", 100, 100, 11, "a"
     (文字列として昇順でソートされています) に変換され、二番目の配列は、
     1, 3, "2", 2, 1 (数値として降順にソートされています) となっています。
    </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>データベースの結果をソートする</title>
    <para>
     この例では、配列 <varname>data</varname>
     の個々の要素がテーブルのひとつの行を表しています。
     これは、データベースのレコードの典型的な形式です。
    </para>
    <para>
     データの例:
    </para>
    <screen>
<![CDATA[
volume | edition
-------+--------
    67 |       2
    86 |       1
    85 |       6
    98 |       2
    86 |       6
    67 |       7
]]>
    </screen>
    <para>
     データは <varname>data</varname> という名前の配列に格納します。
     これは、例えば <function>mysql_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>
     この例では、データを <varname>volume</varname> の降順、
     <varname>edition</varname> の昇順に並べ替えます。
    </para>
    <para>
     私たちが今もっているのは行方向の配列ですが、
     <function>array_multisort</function> で必要なのは列方向の配列です。
     そこで、以下のコードで列方向の配列を得たあとでソートを行います。
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// 列方向の配列を得る
foreach ($data as $key => $row) {
    $volume[$key]  = $row['volume'];
    $edition[$key] = $row['edition'];
}

// 上記のコードの代わりに array_column() を使用できます
$volume  = array_column($data, 'volume');
$edition = array_column($data, 'edition');

// データを volume の降順、edition の昇順にソートする。
// $data を最後のパラメータとして渡し、同じキーでソートする。
array_multisort($volume, SORT_DESC, $edition, SORT_ASC, $data);
?>
]]>
    </programlisting>
    <para>
     データセットの行はソートされ、以下のようになります:
    </para>
    <screen>
<![CDATA[
volume | edition
-------+--------
    98 |       2
    86 |       1
    86 |       6
    85 |       6
    67 |       2
    67 |       7
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>大文字・小文字を区別しないソート</title>
    <para>
     <constant>SORT_STRING</constant> と
     <constant>SORT_REGULAR</constant> はどちらも大文字・小文字を区別し、
     大文字ではじまる文字列が小文字で始まる文字列より前になります。
    </para>
    <para>
     大文字・小文字を区別しないためには、
     元の配列の内容をすべて小文字に変換した配列を用意し、
     それをソートの基準にします。
    </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
-->