# usort

(PHP 4, PHP 5, PHP 7)

usort — 使用用户自定义的比较函数对数组中的值进行排序

### 说明

usort ( array `&$array` , callable `$value_compare_func` ) : bool

本函数将用用户自定义的比较函数对一个数组中的值进行排序。 如果要排序的数组需要用一种不寻常的标准进行排序，那么应该使用此函数。

> Note:

> If two members compare as equal, their relative order in the sorted array is undefined.

> Note: 此函数为 `array` 中的元素赋与新的键名。这将删除原有的键名，而不是仅仅将键名重新排序。

### 参数

`array`

  输入的数组

`cmp_function`

  在第一个参数小于，等于或大于第二个参数时，该比较函数必须相应地返回一个小于，等于或大于 0 的整数。

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

  Returning non-integer values from the comparison function, such as float, will result in an internal cast to integer 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.

### 返回值

成功时返回 `TRUE`， 或者在失败时返回 `FALSE`。

### 范例

Example #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

> Note:

> 很明显在这个小例子中用 sort() 函数更合适。

Example #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");

    while (list($key, $value) = each($fruits)) {
        echo "$fruits[$key]: " . $value["fruit"] . "\n";
    }
    ?>

当排序多维数组时，$a 和 $b 包含到数组第一个索引的引用。

以上例程会输出：

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

Example #3 usort() example using a member function of an object

    <?php
    class TestObj {
        var $name;

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

        /* This is the static comparing function: */
        static function cmp_obj($a, $b)
        {
            $al = strtolower($a->name);
            $bl = strtolower($b->name);
            if ($al == $bl) {
                return 0;
            }
            return ($al > $bl) ? +1 : -1;
        }
    }

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

    usort($a, array("TestObj", "cmp_obj"));

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

以上例程会输出：

    b
    c
    d

Example #4 usort() example using a closure to sort a multi-dimensional array

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

### 参见

- uasort() - 使用用户自定义的比较函数对数组中的值进行排序并保持索引关联
- 数组排序函数对比