usort

(PHP 4, PHP 5, PHP 7, PHP 8)

usortOrdena un array utilizando una función de comparación

Descripción

usort(array &$array, callable $callback): true

Ordena array en el lugar según los valores utilizando una función de comparación definida por el usuario.

Nota:

Si dos miembros se comparan como iguales, ellos mantendrán su orden original. Antes de PHP 8.0.0, su orden relativo en un array ordenado era indefinido.

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

Parámetros

array

El array de entrada.

callback

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

Returning non-integer values from the comparison function, such as float, will result in an internal cast to int of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal.

Valores devueltos

Siempre devuelve true.

Historial de cambios

Versión Descripción
8.2.0 The return type is true now; previously, it was bool.
8.0.0 Si callback espera que se pase un parámetro por referencia, esta función ahora emitirá un E_WARNING.

Ejemplos

Ejemplo #1 Ejemplo con 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 $key => $value) {
echo
"$key: $value\n";
}
?>

El resultado del ejemplo sería:

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

El operador combinado puede ser utilizado para simplificar la comparación interna.

<?php
function cmp($a, $b)
{
return
$a <=> $b;
}

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

usort($a, "cmp");

foreach (
$a as $key => $value) {
echo
"$key: $value\n";
}
?>

Nota:

Evidentemente en este caso trivial, sort() sería más apropiado.

Ejemplo #2 Ordenación con usort() sobre un array multidimensional

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

foreach (
$fruits as $key => $value) {
echo
"\$fruits[$key]: " . $value["fruit"] . "\n";
}
?>

Al ordenar un array multidimensional, $a y $b contienen referencias al primer elemento del array.

El resultado del ejemplo sería:

$fruits[0]: apples
$fruits[1]: grapes
$fruits[2]: lemons

Ejemplo #3 Ordenación con usort() sobre un objeto

<?php
class TestObj {
public
string $name;

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

/* Esta es una función de comparación estática */
static function cmp_obj($a, $b)
{
return
strtolower($a->name) <=> strtolower($b->name);
}
}

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

usort($a, [TestObj::class, "cmp_obj"]);

foreach (
$a as $item) {
echo
$item->name . "\n";
}
?>

El resultado del ejemplo sería:

b
c
d

Ejemplo #4 Ejemplo con usort() utilizando una closure para ordenar un array multidimensional

<?php
$array
[0] = array('key_a' => 'z', 'key_b' => 'c');
$array[1] = array('key_a' => 'x', 'key_b' => 'b');
$array[2] = array('key_a' => 'y', 'key_b' => 'a');

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

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

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

El resultado del ejemplo sería:

y, a
x, b
z, c

Ejemplo #5 Ejemplo de uso del operador combinado con usort().

El operador combinado permite una comparación directa de valores compuestos sobre varios ejes. En el siguiente ejemplo, $people se ordena por apellido, y luego por nombre si el apellido coincide.

<?php
$people
[0] = ['first' => 'Adam', 'last' => 'West'];
$people[1] = ['first' => 'Alec', 'last' => 'Baldwin'];
$people[2] = ['first' => 'Adam', 'last' => 'Baldwin'];

function
sorter(array $a, array $b) {
return [
$a['last'], $a['first']] <=> [$b['last'], $b['first']];
}

usort($people, 'sorter');

foreach (
$people as $person) {
print
$person['last'] . ', ' . $person['first'] . PHP_EOL;
}
?>

El resultado del ejemplo sería:

Baldwin, Adam
Baldwin, Alec
West, Adam

Ver también