usort

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

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

Описание

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

Функция сортирует массив array на месте по значениям путем обработки элементов массива пользовательской функцией сравнения для определения порядка.

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

Замечание: Функция присваивает новые ключи элементам массива, который передали в аргументе array. Функция удалит, а не просто переупорядочит ключи входного массива.

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

array

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

callback
Функция сравнения должна возвращать целое, которое меньше, равно или больше нуля, если первый аргумент является соответственно меньшим, равным или большим, чем второй.
function callback(mixed $a, mixed $b): int
Предостережение

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

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

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

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

Версия Описание
8.2.0 Значение возврата теперь принадлежит типу true; раньше значение принадлежало типу bool.
8.0.0 Функция теперь выдаст ошибку уровня E_WARNING, если параметр 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";
}

?>

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

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

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

Пример #3 Пример сортировки массива функцией usort() через функцию-член объекта

<?php

class TestObj
{
public 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() с оператором «космический корабль»

Оператор «космический корабль» упрощает сравнение составных значений по набору критериев. В следующем примере функция сортирует массив $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

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