aidan Sun Oct 3 07:06:40 2004 EDT
Modified files:
/phpdoc/en/reference/array/functions array-multisort.xml
Log:
Intergrated the user notes into examples
http://cvs.php.net/diff.php/phpdoc/en/reference/array/functions/array-multisort.xml?r1=1.11&r2=1.12&ty=u
Index: phpdoc/en/reference/array/functions/array-multisort.xml
diff -u phpdoc/en/reference/array/functions/array-multisort.xml:1.11
phpdoc/en/reference/array/functions/array-multisort.xml:1.12
--- phpdoc/en/reference/array/functions/array-multisort.xml:1.11 Tue Aug 3
06:24:05 2004
+++ phpdoc/en/reference/array/functions/array-multisort.xml Sun Oct 3 07:06:39
2004
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.11 $ -->
+<!-- $Revision: 1.12 $ -->
<!-- splitted from ./en/functions/array.xml, last change in rev 1.11 -->
<refentry id="function.array-multisort">
<refnamediv>
@@ -8,17 +8,20 @@
</refnamediv>
<refsect1>
<title>Description</title>
- <methodsynopsis>
- <type>bool</type><methodname>array_multisort</methodname>
- <methodparam><type>array</type><parameter>ar1</parameter></methodparam>
- <methodparam
choice="opt"><type>mixed</type><parameter>arg</parameter></methodparam>
- <methodparam
choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
- <methodparam
choice="opt"><type>array</type><parameter>...</parameter></methodparam>
- <!-- Parameters don't need to be passed by reference -->
- </methodsynopsis>
+ <methodsynopsis>
+ <type>bool</type><methodname>array_multisort</methodname>
+ <methodparam><type>array</type><parameter>ar1</parameter></methodparam>
+ <methodparam
choice="opt"><type>mixed</type><parameter>arg</parameter></methodparam>
+ <methodparam
choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
+ <methodparam
choice="opt"><type>array</type><parameter>...</parameter></methodparam>
+ <!-- Parameters don't need to be passed by reference -->
+ </methodsynopsis>
+ <para>
+ &return.success;
+ </para>
<para>
<function>array_multisort</function> can be used to sort several
- arrays at once or a multi-dimensional array according by one of
+ arrays at once or a multi-dimensional array according to one of
more dimensions. Associative (string) keys are maintained while
numerical keys are re-indexed.
</para>
@@ -31,18 +34,18 @@
</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.
+ flexible. The 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><constant>SORT_ASC</constant> - sort in ascending order</simpara>
+ <simpara><constant>SORT_ASC</constant> - Sort in ascending order</simpara>
</listitem>
<listitem>
- <simpara><constant>SORT_DESC</constant> - sort in descending order</simpara>
+ <simpara><constant>SORT_DESC</constant> - Sort in descending order</simpara>
</listitem>
</itemizedlist>
</para>
@@ -50,13 +53,13 @@
Sorting type flags:
<itemizedlist>
<listitem>
- <simpara><constant>SORT_REGULAR</constant> - compare items normally</simpara>
+ <simpara><constant>SORT_REGULAR</constant> - Compare items normally</simpara>
</listitem>
<listitem>
- <simpara><constant>SORT_NUMERIC</constant> - compare items
numerically</simpara>
+ <simpara><constant>SORT_NUMERIC</constant> - Compare items
numerically</simpara>
</listitem>
<listitem>
- <simpara><constant>SORT_STRING</constant> - compare items as strings</simpara>
+ <simpara><constant>SORT_STRING</constant> - Compare items as strings</simpara>
</listitem>
</itemizedlist>
</para>
@@ -66,9 +69,7 @@
only to that array - they are reset to default <constant>SORT_ASC</constant> and
<constant>SORT_REGULAR</constant> before each new array argument.
</para>
- <para>
- &return.success;
- </para>
+
<para>
<example>
<title>Sorting multiple arrays</title>
@@ -78,17 +79,37 @@
$ar1 = array("10", 100, 100, "a");
$ar2 = array(1, 3, "2", 1);
array_multisort($ar1, $ar2);
+
+var_dump($ar1);
+var_dump($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>
+ <screen>
+<![CDATA[
+array(4) {
+ [0]=> string(2) "10"
+ [1]=> string(1) "a"
+ [2]=> int(100)
+ [3]=> int(100)
+}
+array(4) {
+ [0]=> int(1)
+ [1]=> int(1)
+ [2]=> string(1) "2"
+ [3]=> int(3)
+}
+]]>
+ </screen>
</example>
</para>
- <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>
+
<para>
<example>
<title>Sorting multi-dimensional array</title>
@@ -101,14 +122,151 @@
?>
]]>
</programlisting>
+ <para>
+ In this example, after sorting, the first array will contain "10",
+ 100, 100, "a" (it was sorted as strings in ascending order). The
+ second will contain 1, 3, "2", 1 (sorted as numbers, in
+ descending order).
+ </para>
+ <screen>
+<![CDATA[
+array(2) {
+ [0]=> array(4) {
+ [0]=> string(2) "10"
+ [1]=> int(100)
+ [2]=> int(100)
+ [3]=> string(1) "a"
+ }
+ [1]=> array(4) {
+ [0]=> int(1)
+ [1]=> int(3)
+ [2]=> string(1) "2"
+ [3]=> int(1)
+ }
+}
+]]>
+ </screen>
</example>
</para>
+
<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).
+ <example>
+ <title>Sorting database results</title>
+ <para>
+ For this example, each element in the <varname>data</varname>
+ array represents one row in a table. This type of dataset is typical
+ of database records.
+ </para>
+ <para>
+ Example data:
+ </para>
+ <screen>
+<![CDATA[
+volume | edition
+-------+--------
+ 67 | 2
+ 86 | 1
+ 85 | 6
+ 98 | 2
+ 86 | 6
+ 67 | 7
+]]>
+ </screen>
+ <para>
+ The data as an array, called <varname>data</varname>. This would usually,
+ for example, be obtained by looping with
<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>
+ In this example, we will order by <varname>volume</varname> descending,
+ <varname>edition</varname> ascending.
+ </para>
+ <para>
+ We have an array of rows, but <function>array_multisort</function>
+ requires an array of columns, so we use the the below code to obtain the
+ columns, then perform the sorting.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+// Obtain a list of columns
+foreach ($data as $key => $row) {
+ $volume[$key] = $row['volume'];
+ $edition[$key] = $row['edition'];
+}
+
+// Sort the data with volume descending, edition ascending
+// Add $data as the last parameter, to sort by the common key
+array_multisort($volume, SORT_DESC, $edition, SORT_ASC, $data);
+?>
+]]>
+ </programlisting>
+ <para>
+ The dataset is now sorted, and will look like this:
+ </para>
+ <screen>
+<![CDATA[
+volume | edition
+-------+--------
+ 98 | 2
+ 86 | 1
+ 86 | 6
+ 85 | 6
+ 67 | 2
+ 67 | 7
+]]>
+ </screen>
+ </example>
+ </para>
+
+ <para>
+ <example>
+ <title>Case insensitive sorting</title>
+ <para>
+ Both <constant>SORT_STRING</constant> and
+ <constant>SORT_REGULAR</constant> are case sensitive, strings
+ starting with a capital letter will come before strings starting
+ with a lowercase letter.
+ </para>
+ <para>
+ To perform a case insensitve search, we can sort by an all lowercase array.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+$array = array('Alpha', 'atomic', 'Beta', 'bank');
+$array_lowercase = array_map('strtolower', $array);
+
+array_multisort($array_lowercase, SORT_ASC, SORT_STRING, $array, SORT_ASC,
SORT_STRING);
+
+print_r($array);
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+ [0] => Alpha
+ [1] => atomic
+ [2] => bank
+ [3] => Beta
+)
+]]>
+ </screen>
+ </example>
</para>
+
</refsect1>
</refentry>
