usort

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

usort — Trie un tableau en utilisant une fonction de comparaison

Description

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

Trie array sur place suivant les valeurs en utilisant une fonction de comparaison définie par l'utilisateur.

Note:
Si deux membres se comparent comme égaux, ils maintiennent leur ordre original. Antérieur à PHP 8.0.0, leur ordre relatif dans le tableau trié n'est pas défini.

Note: Cette fonction assigne de nouvelles clés aux éléments dans array. Elle effacera toutes les clés existantes qui ont pu être assignées, plutôt que de réarranger les clés.

Liste de paramètres

array: Le tableau d'entrée.
callback: La fonction de comparaison doit retourner un entier inférieur à, égal à, ou supérieur à 0 si le premier argument est considéré comme, respectivement, inférieur à, égal à, ou supérieur au second.

callback(mixed $a, mixed $b): int

Attention
Retourner des valeurs non-entières à partir de la fonction de comparaison, telles que float, entraînera une conversion interne de la valeur de retour du rappel en int. Ainsi, des valeurs telles que 0.99 et 0.1 seront toutes deux converties en une valeur entière de 0, ce qui comparera de telles valeurs comme égales.

Valeurs de retour

Retourne toujours true.

Historique

Version	Description
8.2.0	Le type de retour est maintenant `true`, auparavant il était bool.
8.0.0	Si `callback` attend un paramètre à être passé par référence, cette fonction émet désormais une `E_WARNING`.

Exemples

Exemple #1 Exemple avec 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";
}
?>

L'exemple ci-dessus va afficher :

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

L'opérateur combiné peut être utilisé pour simplifier la comparaison interne.

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

Note:
Évidemment dans ce cas trivial, sort() serait plus approprié.

Exemple #2 Tri avec usort() sur un tableau multidimensionnel

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

L'exemple ci-dessus va afficher :

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

Lors du tri de tableau multidimensionnel, $a et $b contiennent des références sur le premier élément du tableau.

Exemple #3 Tri avec usort() sur un objet

<?php
class TestObj {
    public string $name;

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

    /* Ceci est une fonction de comparaison statique */
    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";
}
?>

L'exemple ci-dessus va afficher :

b
c
d

Exemple #4 Exemple avec usort() en utilisant une closure pour trier un tableau multidimensionnel

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

L'exemple ci-dessus va afficher :

y, a
x, b
z, c

Exemple #5 Exemple d'utilisation de l'opérateur combiné avec usort().

L'opérateur combiné permet une comparaison directe de valeurs composées sur plusieurs axes. Dans l'exemple suivant, $people est trié par nom de famille, puis par prénom si le nom de famille correspond.

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

L'exemple ci-dessus va afficher :

Baldwin, Adam
Baldwin, Alec
West, Adam

Voir aussi

uasort() - Trie un tableau en utilisant une fonction de rappel
uksort() - Trie un tableau par ses clés en utilisant une fonction de rappel
Les fonctions de tri des tableaux