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 su lugar según los valores utilizando una función de comparación definida por el usuario.

Nota:

Si dos miembros se comparan como iguales, mantienen su orden original. Anterior a PHP 8.0.0, su orden relativo en el array ordenado no está definido.

Nota: Esta función asigna nuevas claves a los elementos en array. Eliminará todas las claves existentes que hayan podido ser asignadas, en lugar de reordenar las claves.

Parámetros

array

El array de entrada.

callback

La función de comparación debe retornar un entero menor que, igual a, o mayor que 0 si el primer argumento es considerado, respectivamente, menor que, igual a, o mayor que el segundo.

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

Retornar valores no-entero desde la función de comparación, tales como float, resultará en una conversión interna del valor de retorno del callback a int. Así, valores tales como 0.99 y 0.1 serán convertidos ambos a un valor entero de 0, lo que comparará tales valores como iguales.

Valores devueltos

Retorna siempre true.

Historial de cambios

Versión Descripción
8.2.0 El tipo de retorno es ahora true, anteriormente era bool.
8.0.0 Si callback espera un parámetro a ser pasado por referencia, esta función emite ahora una 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 ejemplo anterior mostrará :

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

El ejemplo anterior mostrará :

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

Al ordenar arrays multidimensionales, $a y $b contienen referencias al primer elemento del array.

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 ejemplo anterior mostrará :

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 ejemplo anterior mostrará :

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 múltiples ejes. En el ejemplo siguiente, $people se ordena por apellido, 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 ejemplo anterior mostrará :

Baldwin, Adam
Baldwin, Alec
West, Adam

Ver también

  • uasort() - Ordena un array utilizando una función de retrollamada
  • uksort() - Ordena un array por sus claves utilizando una función de retrollamada
  • Las funciones de ordenación de arrays