[PHP-DOC] cvs: phpdoc /en/functions array.xml From: Andrei Zmievski (andrei <email protected>)
Date: 07/11/00

andrei Tue Jul 11 12:00:23 2000 EDT

  Modified files:
    /phpdoc/en/functions array.xml
  Log:
  Docs for array_multisort. Woo-hoo.
  
  
Index: phpdoc/en/functions/array.xml
diff -u phpdoc/en/functions/array.xml:1.10 phpdoc/en/functions/array.xml:1.11
--- phpdoc/en/functions/array.xml:1.10 Sat Jul 8 03:52:07 2000
+++ phpdoc/en/functions/array.xml Tue Jul 11 12:00:23 2000
@@ -217,6 +217,115 @@
    </refsect1>
   </refentry>
 
+ <refentry id="function.array-multisort">
+ <refnamediv>
+ <refname>array_multisort</refname>
+ <refpurpose>Sort multiple or multi-dimensional arrays</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>bool <function>array_multisort</function></funcdef>
+ <paramdef>array <parameter>ar1</parameter></paramdef>
+ <paramdef>mixed
+ <parameter><optional>arg</optional></parameter>
+ </paramdef>
+ <paramdef>
+ <parameter><optional>...</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>array_multisort</function> can be used to sort several
+ arrays at once or a multi-dimensional array according by one of
+ more dimensions. It maintains key association when sorting.
+ </para>
+
+ <para>
+ The input arrays are treated as columns of a table to be sorted
+ by rows - this resembles the functionality of SQL ORDER BY
+ clause. The first array is the primary one to sort by. The rows
+ (values) in that array that compare the same are sorted by the
+ next input array, and so on.
+ </para>
+
+ <para>
+ The argument structure of this function is a bit unusual, but
+ flexible. The very first argument has to be an
+ array. Subsequently, each argument can be either an array or a
+ sorting flag from the following lists.
+ </para>
+
+ <para>
+ Sorting order flags:
+ <itemizedlist>
+ <listitem>
+ <simpara>SORT_ASC - sort in ascending order</simpara>
+ </listitem>
+ <listitem>
+ <simpara>SORT_DESC - sort in descending order</simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Sorting type flags:
+ <itemizedlist>
+ <listitem>
+ <simpara>SORT_REGULAR - compare items normally</simpara>
+ </listitem>
+ <listitem>
+ <simpara>SORT_NUMERIC - compare items numerically</simpara>
+ </listitem>
+ <listitem>
+ <simpara>SORT_STRING - compare items as strings</simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ No two sorting flags of the same type can be specified after each
+ array. The sortings flags specified after an array argument apply
+ only to that array - they are reset to default SORT_ASC and
+ SORT_REGULAR after before each new array argument.
+ </para>
+
+ <para>
+ Returns true on success, false on failure.
+ </para>
+
+ <example>
+ <title>Sorting multiple arrays</title>
+ <programlisting role="php">
+$ar1 = array("10", 100, 100, "a");
+$ar2 = array(1, 3, "2", 1);
+array_multisort($ar1, $ar2);
+ </programlisting>
+ <para>
+ In this example, after sorting, the first array will contain 10,
+ "a", 100, 100. The second array will contain 1, 1, 2, "3". The
+ entries in the second array corresponding to the identical
+ entries in the first array (100 and 100) were sorted as well.
+ </para>
+ </example>
+
+ <example>
+ <title>Sorting multi-dimensional array</title>
+ <programlisting role="php">
+$ar = array(array("10", 100, 100, "a"), array(1, 3, "2", 1));
+array_multisort($ar[0], SORT_ASC, SORT_STRING, $ar[1], SORT_NUMERIC, SORT_DESC);
+ </programlisting>
+ <para>
+ In this example, after sorting, the first array will contain 10,
+ 100, 100, "a" (it was sorted as strings in ascending order), and
+ the second one will contain 1, 3, "2", 1 (sorted as numbers, in
+ descending order).
+ </para>
+ </example>
+ </refsect1>
+ </refentry>
+
   <refentry id="function.array-pad">
    <refnamediv>
     <refname>array_pad</refname>