usort

(PHP 4, PHP 5, PHP 7)

usort — Ordena un array según sus valores usando una función de comparación definida por el usuario

Descripción

usort ( array &$array , callable $value_compare_func ) : bool

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.

Nota:

Si dos miembros se comparan como iguales, su orden relativo en el array oredenado será indefinido.

Nota: Esta función asigna nuevas clave a los elemenos del array. Eliminará cualquier clave existente que haya sido asignada, en lugar de reordenar las claves.

Parámetros

array

El array de entrada.

value_compare_func

La función de comparación debe devolver un entero menor, igual o mayor que cero si el primer argumento se considera que sea respectivamente menor, igual o mayor que el segundo. Observe que antes de PHP 7.0.0 este entero debía estar en el rango de -2147483648 a 2147483647.

callback ( mixed $a, mixed $b ) : int
Precaución

La devolución de valores que no sean de tipo integer por parte de la función de comparación, como float, resultará en una conversión interna a integer 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.

Valores devueltos

Devuelve TRUE en caso de éxito o FALSE en caso de error.

Ejemplos

Ejemplo #1 Ejemplo de usort()

<?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";
}
?>

El resultado del ejemplo sería:

0: 1
1: 2
2: 3
3: 5
4: 6

Nota:

Obviamente, en este caso tan trivial, la función sort() sería más apropiada.

Ejemplo #2 Ejemplo de usort() usando un array multidimensional

<?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";
}
?>

Cuando se ordena un array multidimensional, $a y $b contienen referencias al primer índice del array.

El resultado del ejemplo sería:

$frutas[0]: limones
$frutas[1]: manzanas
$frutas[2]: uvas

Ejemplo #3 Ejemplo de usort() usando una función miembro de un objeto

<?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";
}
?>

El resultado del ejemplo sería:

b
c
d

Ejemplo #4 Ejemplo de usort() usando un cierre para ordenar un array multidimensional

<?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('clave_b'));

foreach ($array as $item) {
    echo $item['clave_a'] . ', ' . $item['clave_b'] . "\n";
}
?>

El resultado del ejemplo sería:

y, a
x, b
z, c

Ver también