archived-doc-es/reference/array/functions/usort.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 15bd95f5d1026b858cb7f02ec490d583e6a0f796 Maintainer: seros Status: ready -->
<!-- Reviewed: no Maintainer: seros -->
<refentry xml:id="function.usort" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>usort</refname>
  <refpurpose>Ordena un array según sus valores usando una función de comparación definida por el usuario</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>callable</type><parameter>cmp_function</parameter></methodparam>
  </methodsynopsis>
  <para>
   Esta función ordenará un array según sus valores usando una función de comparación
   definida por el usuario. Si el array que se desea ordenar necesita ser ordenado por
   algún criterio no trivial, debería usar esta función.
  </para>
  <note>
   <para>
    Si dos miembros se comparan como iguales, su orden relativo en el array ordenado es indefinido.
   </para>
  </note>
  &note.no-key-association;
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>array</parameter></term>
     <listitem>
      <para>
       El array de entrada.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>cmp_function</parameter></term>
     <listitem>
      <para>
       &return.callbacksort;
      </para>
      &callback.cmp;
      <caution>
       <para>
        La devolución de valores que <emphasis>no sean de tipo integer</emphasis> por parte
        de la función de comparación, como <type>float</type>, resultará en una conversión
        interna a <type>integer</type> del valor devuelto por la llamada de retorno. Así, valores
        como 0.99 y 0.1 serán convertidos al valor de tipo integer 0, lo cual hará que la
        comparación de tales valores sea igual.
       </para>
      </caution>
     </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>
        Se introdujo un nuevo algoritmo de ordenación. La función <parameter>cmp_function</parameter>
        no mantiene el orden original de los elementos comparadados como iguales.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example xml:id="function.usort.examples.basic">
    <title>Ejemplo de <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");

foreach ($a as $clave => $valor) {
    echo "$clave: $valor\n";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
0: 1
1: 2
2: 3
3: 5
4: 6
]]>
    </screen>
   </example>
  </para>
  <note>
   <para>
    Obviamente, en este caso tan trivial, la función <function>sort</function>
    sería más apropiada.
   </para>
  </note>
  <para>
   <example xml:id="function.usort.examples.multi">
    <title>
     Ejemplo de <function>usort</function> usando un array multidimensional
    </title>
    <programlisting role="php">
<![CDATA[
<?php
function cmp($a, $b)
{
    return strcmp($a["fruta"], $b["fruta"]);
}

$frutas[0]["fruta"] = "uvas";
$frutas[1]["fruta"] = "limones";
$frutas[2]["fruta"] = "manzanas";

usort($frutas, "cmp");

while (list($clave, $valor) = each($frutas)) {
    echo "\$frutas[$clave]: " . $valor["fruta"] . "\n";
}
?>
]]>
    </programlisting>
    <para>
     Cuando se ordena un array multidimensional, <varname>$a</varname> y
     <varname>$b</varname> contienen referencias al primer índice del array.
    </para>
    &example.outputs;
    <screen>
<![CDATA[
$frutas[0]: limones
$frutas[1]: manzanas
$frutas[2]: uvas
]]>
    </screen>
   </example>
  </para>
  <para>
   <example xml:id="function.usort.examples.object">
    <title>
     Ejemplo de <function>usort</function> usando una función miembro de un objeto
    </title>
    <programlisting role="php">
<![CDATA[
<?php
class ObjPrueba {
    var $nombre;

    function ObjPrueba($nombre)
    {
        $this->nombre = $nombre;
    }

    /* Ésta es la función de comparación estática: */
    static function cmp_obj($a, $b)
    {
        $al = strtolower($a->nombre);
        $bl = strtolower($b->nombre);
        if ($al == $bl) {
            return 0;
        }
        return ($al > $bl) ? +1 : -1;
    }
}

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

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

foreach ($a as $elemento) {
    echo $elemento->nombre . "\n";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
b
c
d
]]>
    </screen>
   </example>
   <example xml:id="function.usort.examples.closure">
    <title>
     Ejemplo de <function>usort</function> usando un <link linkend="functions.anonymous">cierre</link>
     para ordenar un array multidimensional
    </title>
    <programlisting role="php">
<![CDATA[
<?php
$array[0] = array('clave_a' => 'z', 'clave_b' => 'c');
$array[1] = array('clave_a' => 'x', 'clave_b' => 'b');
$array[2] = array('clave_a' => 'y', 'clave_b' => 'a');

function build_sorter($clave) {
    return function ($a, $b) use ($clave) {
        return strnatcmp($a[$clave], $b[$clave]);
    };
}

usort($array, build_sorter('key_b'));

foreach ($array as $item) {
    echo $item['clave_a'] . ', ' . $item['clave_b'] . "\n";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
y, a
x, b
z, c
]]>
    </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
-->