usort.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- splitted from ./it/functions/array.xml, last change in rev 1.1 -->
<!-- last change to 'usort' in en/ tree in rev 1.2 -->
<!-- EN-Revision: n/a Maintainer: cucinato Status: ready -->
<!-- OLD-Revision: 1.173/EN.1.2 -->
  <refentry xml:id="function.usort" xmlns="http://docbook.org/ns/docbook">
   <refnamediv>
    <refname>usort</refname>
    <refpurpose>
     Ordina un array mediante una funzione definita dall'utente
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descrizione</title>
     <methodsynopsis>
      <type>bool</type><methodname>usort</methodname>
      <methodparam><type>array</type><parameter>&amp;array</parameter></methodparam>
      <methodparam><type>callback</type><parameter>cmp_function</parameter></methodparam>
     </methodsynopsis>
    <para>
     Ordina i valori di un array mediante una
     funzione di comparazione definita dall'utente. Se si vuole ordinare un array
     con dei criteri non usuali, si deve usare
     questa funzione.
    </para>
    <para>
     La funzione di comparazione deve restituire un intero minore, uguale
     o superiore a zero se il primo elemento è da considerarsi
     rispettivamente minore, uguale o maggiore del 
     secondo.
    </para>
    <para>
     <note>
      <para>
       Se due parametri vengono valutati come uguali, il loro ordinamento nell'array ordinato è indefinito.
       Fino al PHP 4.0.6 le funzioni definite dall'utente mantenevano l'ordine originario per
       questi elementi, ma con il nuovo algoritmo di ordinamento introdotto con la versione 4.1.0 questo
       non succede più dal momento che non c'è un modo per ottenerlo in maniera efficiente.
      </para>
     </note>
    </para>
    <para>
     &return.success;
    </para>
    <para>
     <example>
      <title>esempio di <function>usort</function></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");

while (list($chiave, $valore) = each($a)) {
    echo "$chiave: $valore\n";
}
?>
]]>
      </programlisting>
      <para>
       Questo esempio mostrerà:
      </para>
      <screen>
<![CDATA[
0: 1
1: 2
2: 3
3: 5
4: 6
]]>
      </screen>
     </example>
    </para>
    <note>
     <para>
      Ovviamente, in questo caso banale di ordinamento decrescente la funzione <function>sort</function>
      sarebbe stata più appropriata.
     </para>
    </note>
    <para>
     <example>
      <title>
       esempio di <function>usort</function> con un array multidimensionale
      </title>
      <programlisting role="php">
<![CDATA[
<?php
function cmp($a, $b) 
{
    return strcmp($a["frutto"], $b["frutto"]);
}

$frutti[0]["frutto"] = "limoni";
$frutti[1]["frutto"] = "arance";
$frutti[2]["frutto"] = "uva";

usort($frutti, "cmp");

while (list($chiave, $valore) = each($frutti)) {
    echo "\$frutti[$chiave]: " . $valore["frutto"] . "\n";
}
?>
]]>
      </programlisting>
      <para>
       Quando si ordina un array multidimensionale, <varname>$a</varname> e
       <varname>$b</varname> contengono riferimenti al primo indice dell'array.
      </para>
      <para>
       Questo esempio mostrerà:
      </para>
      <screen>
<![CDATA[
$frutti[0]: arance
$frutti[1]: limoni
$frutti[2]: uva
]]>
      </screen>
     </example>
    </para>

    <para>
     <example>
      <title>
       esempio di <function>usort</function> usando una funzione membro di un oggetto
      </title>
      <programlisting role="php">
<![CDATA[
<?php
class OggettoTest {
    var $nome;

    function OggettoTest($nome) 
    {
        $this->nome = $nome;
    }

    /* Questa è la funzione statica di comparazione: */
    function comp_ogg($a, $b) 
    {
        $al = strtolower($a->nome);
        $bl = strtolower($b->nome);
        if ($al == $bl) {
            return 0;
        }
        return ($al > $bl) ? +1 : -1;
    }
}

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

usort($a, array("OggettoTest", "comp_ogg"));

foreach ($a as $voce) {
    echo $voce->nome."\n";
}
?>
]]>
      </programlisting>
      <para>
       Questo esempio mostrerà:
      </para>
      <screen>
<![CDATA[
b
c
d
]]>
      </screen>
     </example>
    </para>

    <para>
     Vedere anche <function>uasort</function>,
     <function>uksort</function>, <function>sort</function>,
     <function>asort</function>,
     <function>arsort</function>,<function>ksort</function>,
     <function>natsort</function> e <function>rsort</function>.
    </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
-->