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 __construct(string $locale)
public asort(array &$array, int $flags = Collator::SORT_REGULAR): bool
public compare(string $string1, string $string2): int|false
public static create(string $locale): ?Collator
public getAttribute(int $attribute): int|false
public getErrorCode(): int|false
public getErrorMessage(): string|false
public getLocale(int $type): string|false
public getSortKey(string $string): string|false
public getStrength(): int
public setAttribute(int $attribute, int $value): bool
public setStrength(int $strength): bool
public sort(array &$array, int $flags = Collator::SORT_REGULAR): bool
public sortWithSortKeys(array &$array): bool
}

Constantes pré-definidas

Collator::FRENCH_COLLATION

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:

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

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

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:

Example #3 Regras de CASE_FIRST

  • C=X or C=L "china" < "China" < "denmark" < "Denmark"
  • C=U "China" < "china" < "Denmark" < "denmark"
Collator::CASE_LEVEL

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:

Example #4 Regras de CASE_LEVEL

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

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::STRENGTH

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::HIRAGANA_QUATERNARY_MODE

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::NUMERIC_COLLATION

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::DEFAULT_VALUE
Collator::PRIMARY
Collator::SECONDARY
Collator::TERTIARY
Collator::DEFAULT_STRENGTH
Collator::QUATERNARY
Collator::IDENTICAL
Collator::OFF
Collator::ON
Collator::SHIFTED
Collator::NON_IGNORABLE
Collator::LOWER_FIRST
Collator::UPPER_FIRST
Collator::SORT_REGULAR

Collator::SORT_STRING

Collator::SORT_NUMERIC

Table of Contents