# A classe Collator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Introdução

Fornece capacidade de comparação de strings com suporte ao ordenamento apropriado de acordo com a localidade.

## Resumo da classe

class Collator {
/* Constantes */
public const int DEFAULT_VALUE;
public const int PRIMARY;
public const int SECONDARY;
public const int TERTIARY;
public const int DEFAULT_STRENGTH;
public const int QUATERNARY;
public const int IDENTICAL;
public const int OFF;
public const int ON;
public const int SHIFTED;
public const int NON_IGNORABLE;
public const int LOWER_FIRST;
public const int UPPER_FIRST;
public const int FRENCH_COLLATION;
public const int ALTERNATE_HANDLING;
public const int CASE_FIRST;
public const int CASE_LEVEL;
public const int NORMALIZATION_MODE;
public const int STRENGTH;
public const int HIRAGANA_QUATERNARY_MODE;
public const int NUMERIC_COLLATION;
public const int SORT_REGULAR;
public const int SORT_STRING;
public const int SORT_NUMERIC;
/* Métodos */
public function __construct(string `$locale`)
public function asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function compare(string `$string1`, string `$string2`): int|false
public static function create(string `$locale`): ?Collator
public function getAttribute(int `$attribute`): int|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public function getLocale(int `$type`): string|false
public function getSortKey(string `$string`): string|false
public function getStrength(): int
public function setAttribute(int `$attribute`, int `$value`): bool
public function setStrength(int `$strength`): true
public function sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function sortWithSortKeys(array `&$array`): bool
}

## Constantes predefinidas

`Collator::FRENCH_COLLATION` int

  Ordena strings com diferentes acentuações a partir do final da string. Este atributo é automaticamente definido para ON (ligado) para as localidades francesas e algumas outras. Usuários normalmente não precisam definir explicitamente este atributo. Há um custo de desempenho de comparação de strings quando definida para ON, mas o comprimento da chave de ordenação não é afetado. Os valores possíveis são:

  - `Collator::ON`
  - `Collator::OFF`(padrão)
  - `Collator::DEFAULT_VALUE`

  Exemplo #1 Regras da FRENCH_COLLATION

  - F=OFF cote < coté < côte < côté
  - F=ON cote < côte < coté < côté
`Collator::ALTERNATE_HANDLING`

  O atributo alternativo é usado para controlar o gerenciamento dos chamados caracteres variáveis na UCA: espaços em branco, pontuações e símbolos. Se ALTERNATE_HANDLING (A) for definido para NON_IGNORABLE (N), as diferenças entre estes caracteres são da mesma importância que as diferenças entre letras. Se ALTERNATE_HANDLING for definida para SHIFTED (S), estes caracteres são somente de importância menor. O valor SHIFTED é frequentemente usado em combinação com STRENGTH definida para set to QUATERNARY. Neste caso, espaços em branco, pontuações e símbolos são considerados ao comparar strings, mas somente se todos os outros aspectos das strings (letras base, acentos e forma) forem idênticos. Se ALTERNATE_HANDLING não for definida para SHIFTED, não haverá diferença entre uma STRENGTH de 3 e uma STRENGTH de 4. Para mais informações e exemplos, consulte "Variable_Weighting" na » UCA. A razão pela qual os valores para ALTERNATE_HANDLING não são simplesmente ON (ligado) e OFF (desligado) é que valores adicionais podem ser necessários no futuro. A opção BLANKED da UCA é expressa com STRENGTH de 3, e ALTERNATE_HANDLING definida para SHIFTED. O padrão para a maioria das localidades é NON_IGNORABLE. Se SHIFTED for selecionado, pode ser mais lento se houver muitas strings que são as mesmas exceto pela pontuação; o comprimento da chave de ordenação não será afetado a menos que o nível de STRENGHT seja também aumentado.

  Os valores possíveis são:

  - `Collator::NON_IGNORABLE`(padrão)
  - `Collator::SHIFTED`
  - `Collator::DEFAULT_VALUE`

  Exemplo #2 Regras de ALTERNATE_HANDLING

  - S=3, A=N di Silva < Di Silva < diSilva < U.S.A. < USA
  - S=3, A=S di Silva = diSilva < Di Silva < U.S.A. = USA
  - S=4, A=S di Silva < diSilva < Di Silva < U.S.A. < USA
`Collator::CASE_FIRST` int

  O atributo CASE_FIRST é usado para controlar se letras maiúsculas vêm antes de letras minúsculas ou vice-versa, na ausência de outras diferenças nas strings. Os valores possíveis são UPPER_FIRST (maiúsculas primeiro - U) e LOWER_FIRST (minúsculas primeiro - L), mais o DEFAULT (padrão) e OFF (desligado - X). Quase não há diferença entre as opções OFF e LOWER_FIRST em termos de resultados, portanto tipicamente os usuários não usarão LOWER_FIRST: apenas OFF ou UPPER_FIRST. (Os interessados nas diferenças detalhadas entre X e L devem consultar a `Collation Customization` - Customização de Agrupamento). Especificar L ou U não afetará o desempenho de comparação de strings, mas afetará o comprimento da chave de ordenação.

  Os valores possíveis são:

  - `Collator::OFF`(padrão)
  - `Collator::LOWER_FIRST`
  - `Collator::UPPER_FIRST`
  - `Collator:DEFAULT`

  Exemplo #3 Regras de CASE_FIRST

  - C=X ou C=L "china" < "China" < "denmark" < "Denmark"
  - C=U "China" < "china" < "Denmark" < "denmark"
`Collator::CASE_LEVEL` int

  O atributo CASE_LEVEL é usado quando os acentos são ignorados mas as maiúsculas/minúsculas não são. Nesta situação, deve-se definir STRENGTH para PRIMARY, e CASE_LEVEL para ON. Na maioria das localidades, esta configuração é OFF por padrão. Existe um pequeno impacto no desempenho de comparação de strings e na chave de ordenação se este atributo for definido para ON.

  Os valores possíveis são:

  - `Collator::OFF`(padrão)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`

  Exemplo #4 Regras de CASE_LEVEL

  - S=1, E=X role = Role = rôle
  - S=1, E=O role = rôle < Role
`Collator::NORMALIZATION_MODE` int

  A configuração NORMALIZATION_MODE determina se o texto está completamente normalizado ou não na comparação. Mesmo se a configuração esteja em OFF (que é o padrão para muitas localidades), texto como representado em uso comum irá comparar corretamente (para detalhes, consulte UTN #5). Somente se as marcas de acentos estiverem em ordem não canônica haverá problema. Se a configuração estiver em ON, os melhores resultados são garantidos para todas as entradas de texto possíveis. Existe um custo médio de desempenho na comparação de strings se este atributo estiver em ON, dependendo da frequência de sequências que requerem normalização. Não há efeito significativo no comprimento da chave de ordenação. Se for sabido que o texto de entrada está nas formas de normalização NFD ou NFKD, não há necessidade de habilitar esta opção de normalização.

  Os valores possíveis são:

  - `Collator::OFF`(padrão)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::STRENGTH` int

  O Serviço de Agrupamento ICU suporta vários níveis de comparação, chamados também de "Strengths" (forças). Ter estas categorias possibilita à ICU ordenar as strings de forma precisa conforme as convenções locais. Entretanto, ao permitir que os níveis sejam seletivamente empregados, a pesquisa por uma string no texto pode ser realizada com várias condições de correspondência. Para informações mais detalhadas, consulte o capítulo collator_set_strength().

  Os valores possíveis são:

  - `Collator::PRIMARY`
  - `Collator::SECONDARY`
  - `Collator::TERTIARY`(padrão)
  - `Collator::QUATERNARY`
  - `Collator::IDENTICAL`
  - `Collator::DEFAULT_VALUE`
`Collator::HIRAGANA_QUATERNARY_MODE` int

  Compatibilidade com JIS x 4061 requer a introdução de um nível adicional para distinguir caracteres Hiragana e Katakana. Se for requerida compatibilidade com o esse padrão, este atributo deve ser definido para ON, e a STRENGTH deve ser definida para QUATERNARY. Isto afetará o comprimento da chave de ordenação e desempenho de comparação de strings.

  Os valores possíveis são:

  - `Collator::OFF`(padrão)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::NUMERIC_COLLATION` int

  Quando definido para ON, este atributo gera uma chave de agrupamento para o valor numérico de substrings de dígitos. Esta é uma maneira de obter '100' ordenado DEPOIS de '2'.

  Os valores possíveis são:

  - `Collator::OFF`(padrão)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::DEFAULT_VALUE` int
`Collator::PRIMARY` int
`Collator::SECONDARY` int
`Collator::TERTIARY` int
`Collator::DEFAULT_STRENGTH` int
`Collator::QUATERNARY` int
`Collator::IDENTICAL` int
`Collator::OFF` int
`Collator::ON` int
`Collator::SHIFTED` int
`Collator::NON_IGNORABLE` int
`Collator::LOWER_FIRST` int
`Collator::UPPER_FIRST` int
`Collator::SORT_REGULAR` int

`Collator::SORT_STRING` int

`Collator::SORT_NUMERIC` int

## Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | As constantes de classe agora são tipadas.

## Índice

- Collator::asort — Ordena array mantendo associação de índice
- Collator::compare — Compara duas strings Unicode
- Collator::__construct — Cria um agrupador (Collator)
- Collator::create — Cria um agrupador
- Collator::getAttribute — Obtém o valor de atributo de um agrupador
- Collator::getErrorCode — Obtém o último código de erro do agrupador
- Collator::getErrorMessage — Obtém o texto para o último código de erro do agrupador
- Collator::getLocale — Obtém o nome da localidade do agrupador
- Collator::getSortKey — Obtém a chave de ordenação de uma string
- Collator::getStrength — Obtém a força atual de agrupamento
- Collator::setAttribute — Define atributo do agrupador
- Collator::setStrength — Define a força do agrupador
- Collator::sort — Ordena um array usando o agrupador especificado
- Collator::sortWithSortKeys — Ordena um array usando agrupador e chaves de ordenação especificados

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open