usort

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

    usort — Сортирует массив по значениям используя пользовательскую функцию для сравнения элементов

    Описание

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

    Сортирует array по значениям, используя предоставленную пользователем функцию сравнения для определения порядка.

    Замечание:

    Функция сохраняет первоначальный порядок элементов, если при сравнении значения двух элементов равны. До PHP 8.0.0 порядок элементов в отсортированном массиве оставался неопределённым.

    Замечание: Эта функция присваивает новые ключи элементам array. Она удалит все существующие ключи, а не просто переупорядочит их.

    Список параметров

    array

    Входной массив.

    callback

    Функция сравнения должна возвращать целое, которое меньше, равно или больше нуля, если первый аргумент является соответственно меньшим, равным или большим, чем второй.

    callback(mixed$a, mixed$b): int
    Предостережение

    Возвращение нецелых значений из функции сравнения, таких как число с плавающей точкой (float), приведёт к внутреннему приведению возвращаемого значения callback-функции к целому числу (int). Таким образом, значения 0.99 и 0.1 будут приведены к целочисленному значению 0, что позволит сравнить эти значения как равные.

    Возвращаемые значения

    Функция всегда возвращает true.

    Список изменений

    ВерсияОписание
    8.2.0 Тип возвращаемого значения теперь true; ранее было bool.
    8.0.0 Теперь функция выдаст ошибку уровня E_WARNING, если параметр callback-функции, переданной в параметр callback, ожидает передачу значения по ссылке.

    Примеры

    Пример #1 Пример использования 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";
    }
    ?>

    Результат выполнения приведённого примера: 

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

    Для ещё большего упрощения внутреннего сравнения можно использовать оператор spaceship (космический корабль).

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

    Замечание:

    Очевидно, что для этого тривиального случая более подходит функция sort().

    Пример #2 Пример использования функции usort() с многомерными массивами

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

    При сортировке многомерного массива переменные $a и $b содержат ссылки на первые два индекса массива.

    Результат выполнения приведённого примера: 

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

    Пример #3 Пример использования usort() с методом класса

    <?php
    class TestObj {
    private     string $name;

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


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

    Результат выполнения приведённого примера: 

    b c d

    Пример #4 Пример использования функции usort() с применением анонимной функции для сортировки многомерного массива

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

    Результат выполнения приведённого примера: 

    y, a x, b z, c

    Пример #5 Пример использования usort() с оператором spaceship (космический корабль)

    Оператор spaceship (космический корабль) позволяет прямолинейно сравнивать составные значения по нескольким осям. В следующем примере $people сортируется по фамилии, а затем по имени, если фамилия совпадает.

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

    Результат выполнения приведённого примера: 

    Baldwin, Adam Baldwin, Alec West, Adam

    Смотрите также

    To Top