usort

(PHP 4, PHP 5)

usort — Ordena um array pelos valores utilizando uma função de comparação definida pelo usuário

Descrição

bool usort ( array &$array , string $cmp_function )

Essa função irá ordenar um array pelos valores usando uma função de classificação definida pelo usuário. Se o array precisar ser ordenado utilizando um critério não trivial, você deve usar essa função.

Note:

Se dois elementos são considerados iguais, a ordem deles fica indefinida no array resultante.

Note: Esta função define novas chaves para os elementos em array. Ela irá remover qualquer chave que você tenha definido, ao invés de simplesmente reordenar as chaves.

Parâmetros

array

The input array.

cmp_function

A função de comparação deve retornar um inteiro menor, igual ou maior que zero se o primeiro argumento for considerado respectivamente menor, igual, ou maior que o segundo.

Valor Retornado

Retorna TRUE em caso de sucesso ou FALSE em caso de falha.

Changelog

Versão Descrição
4.1.0 O novo algoritmo de ordenação foi introduzido. A cmp_function não mantem a ordenação original para elementos comparando como igual.

Exemplos

Example #1 Exemplo da 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 "$chave: $valor\n";
}
?>

O exemplo acima irá imprimir:

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

Note:

Obviamente que nesse caso trivial a função sort() seria mais apropriada.

Example #2 Exemplo de usort() usando um array multi-dimensional

<?php
function cmp($a, $b)
{
    return strcmp($a["fruta"], $b["fruta"]);
} 

$frutas[0]["fruta"] = "limoes";
$frutas[1]["fruta"] = "abacaxis";
$frutas[2]["fruta"] = "goiabas";

usort($frutas, "cmp"); 

while (list($chave, $valor) = each($frutas)) {
    echo "\$frutas[$chave]: " . $valor["fruta"] . "\n";
}
?>

Na ordenação de um array multi-dimensional, $a e $b contém referências para o primeiro índice do array.

O exemplo acima irá imprimir:

$fruits[0]: abacaxis
$fruits[1]: goiabas
$fruits[2]: limoes

Example #3 Exemplo de usort() usando uma função membro de um objeto

<?php
class TestObj {
    var $name;

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

    /* Essa é a função estática de comparação */
    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";
}
?>

O exemplo acima irá imprimir:

b
c
d

Veja Também

  • uasort() - Ordena um array utilizando uma função de comparação definida pelo usuário e mantendo as associações entre chaves e valores
  • uksort() - Ordena um array pelas chaves utilizando uma função de comparação definida pelo usuário.
  • sort() - Ordena um array
  • asort() - Ordena um array mantendo a associação entre índices e valores
  • arsort() - Ordena um array em ordem descrescente mantendo a associação entre índices e valores
  • ksort() - Ordena um array pelas chaves
  • natsort() - Ordena um array utilizando o algoritmo da "ordem natural"
  • rsort() - Ordena um array em ordem descrescente