<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297028 $ -->
<refentry xml:id="function.usort" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>usort</refname>
  <refpurpose>Sort an array by values using a user-defined comparison function</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>usort</methodname>
   <methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
   <methodparam><type>callback</type><parameter>cmp_function</parameter></methodparam>
  </methodsynopsis>
  <para>
   This function will sort an array by its values using a user-supplied
   comparison function.  If the array you wish to sort needs to be sorted by
   some non-trivial criteria, you should use this function.
  </para>
  <note>
   <para>
    If two members compare as equal, their order in the sorted array is undefined.
   </para>
  </note>
  &note.no-key-association;
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>array</parameter></term>
     <listitem>
      <para>
       The input array.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>cmp_function</parameter></term>
     <listitem>
      <para>
       The comparison function must return an integer less than, equal to, or
       greater than zero if the first argument is considered to be
       respectively less than, equal to, or greater than the second.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>4.1.0</entry>
       <entry>
        A new sort algorithm was introduced. The <parameter>cmp_function</parameter>
        doesn't keep the original order for elements comparing as equal.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>usort</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
function cmp($a, $b)
{
    if ($a == $b) {
        return 0;
    }
    return ($a < $b) ? -1 : 1;
}

$a = array(3, 2, 5, 6, 1);

usort($a, "cmp");

foreach ($a as $key => $value) {
    echo "$key: $value\n";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
0: 1
1: 2
2: 3
3: 5
4: 6
]]>
    </screen>
   </example>
  </para>
  <note>
   <para>
    Obviously in this trivial case the <function>sort</function>
    function would be more appropriate.
   </para>
  </note>
  <para>
   <example>
    <title>
     <function>usort</function> example using multi-dimensional array
    </title>
    <programlisting role="php">
<![CDATA[
<?php
function cmp($a, $b)
{
    return strcmp($a["fruit"], $b["fruit"]);
}

$fruits[0]["fruit"] = "lemons";
$fruits[1]["fruit"] = "apples";
$fruits[2]["fruit"] = "grapes";

usort($fruits, "cmp");

while (list($key, $value) = each($fruits)) {
    echo "\$fruits[$key]: " . $value["fruit"] . "\n";
}
?>
]]>
    </programlisting>
    <para>
     When sorting a multi-dimensional array, <varname>$a</varname> and
    <varname>$b</varname> contain references to the first index of the array.
    </para>
    &example.outputs;
    <screen>
<![CDATA[
$fruits[0]: apples
$fruits[1]: grapes
$fruits[2]: lemons
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>
     <function>usort</function> example using a member function of an object
    </title>
    <programlisting role="php">
<![CDATA[
<?php
class TestObj {
    var $name;

    function TestObj($name)
    {
        $this->name = $name;
    }

    /* This is the static comparing function: */
    static function cmp_obj($a, $b)
    {
        $al = strtolower($a->name);
        $bl = strtolower($b->name);
        if ($al == $bl) {
            return 0;
        }
        return ($al > $bl) ? +1 : -1;
    }
}

$a[] = new TestObj("c");
$a[] = new TestObj("b");
$a[] = new TestObj("d");

usort($a, array("TestObj", "cmp_obj"));

foreach ($a as $item) {
    echo $item->name . "\n";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
b
c
d
]]>
    </screen>
   </example>
  </para>
 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>uasort</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
-->