# La classe Collator

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

## Introduction

Fournit des outils de comparaisons de chaînes, avec le support des conventions locales pour les tris.

## Synopsis de la 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éthodes */
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`): true
public sort(array `&$array`, int `$flags` = Collator::SORT_REGULAR): bool
public sortWithSortKeys(array `&$array`): bool
}

## Constantes pré-définies

`Collator::FRENCH_COLLATION` int

  Trie les chaînes avec différents accents, sur la fin de la chaîne. Cet attribut est automatiquement configuré à On pour les locales françaises, et quelques autres. Les utilisateurs n'ont pas besoin de configurer explicitement cet attribut. Il y a un coût de performances lors de la comparaison des chaînes quand cet attribut est à On, mais la taille des clés de tris est inchangée. Les valeurs possibles sont :

  - `Collator::ON`
  - `Collator::OFF`(par défaut)
  - `Collator::DEFAULT_VALUE`

  Exemple #1 Règles de FRENCH_COLLATION

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

  L'attribut alterné est utilisé pour contrôler la gestion des caractères variables de UCA : les espaces blancs, la ponctuation et les symboles. Si Alternate est configuré à NonIgnorable (N), alors les différences entre ces caractères sont de la même importance que les différences entre les lettres. Si Alternate est configuré à Shifted (S), alors ces caractères seront d'importance mineur. La valeur Shifted est souvent utilisée conjointement avec Quaternary qui vaut Strength. Dans ce cas, les espaces blancs, la ponctuation et les symboles sont considérés lors de la comparaison, mais uniquement si les autres aspects de la chaînes (lettres de base, accents et casse) sont tous identiques. Si Alternate n'est pas configuré à Shifted, il n'y a alors pas de différence entre une Strength de 3 et une Strength de 4. Pour plus d'information et d'exemples, voyez Variable_Weighting dans » UCA. La raison qui fait que les valeurs de Alternate ne sont pas seulement On et Off est que des valeurs supplémentaires pour Alternate pourraient être ajoutées à l'avenir. L'option UCA Blanked est exprimée avec une valeur de Strength à 3, et Alternate configuré à Shifted. La valeur par défaut pour la majorité des locales est NonIgnorable. Si Shifted est sélectionné, il peut être plus lent s'il y a de nombreuses chaînes qui sont identiques, sauf pour la ponctuation : la taille de la clé de tri sera inchangée, à mois que le niveau de Strength ne soit élevé.

  Les valeurs possibles sont :

  - `Collator::NON_IGNORABLE`(par défaut)
  - `Collator::SHIFTED`
  - `Collator::DEFAULT_VALUE`

  Exemple #2 Règles 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

  L'attribut Case_First est utilisé pour contrôler le fait que les majuscules doivent être considérées comme avant les minuscules, et vice-versa, en l'absence d'autres discriminant. Les valeurs possibles sont Uppercase_First (U) et Lowercase_First (L), plus les valeurs standards Default et Off. Il n'y a presque pas de différence entre Off et Lowercase_First en termes de résultats, ce qui fait que les utilisateurs typiques n'utiliseront pas Lowercase_First : uniquement Off ou Uppercase_First. (ceux qui sont intéressés par les différences entre X et L devront consulter la section `Collation Customization`). Spécifier L ou U ne va pas changer les performances de comparaison, mais va affecter la taille de la clé de tri.

  Les valeurs possibles sont :

  - `Collator::OFF`(par défaut)
  - `Collator::LOWER_FIRST`
  - `Collator::UPPER_FIRST`
  - `Collator:DEFAULT`

  Exemple #3 Règles CASE_FIRST

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

  L'attribut Case_Level est utilisé pour ignorer les accents, mais pas la casse. Dans ces situations, mettez l'attribut Strength à Primary, et Case_Level à On. Dans la plupart des locales, cet attribut est à Off par défaut. Il y a un petit coût de performances pour la comparaison des chaînes, un un impact sur la taille des index de tri si cet attribut est à On.

  Les valeurs possibles sont :

  - `Collator::OFF`(par défaut)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`

  Exemple #4 Règles CASE_LEVEL

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

  L'attribut Normalization détermine s'il faut normaliser totalement le texte ou non, pour la comparaison. Même si cet attribut à Off (ce qui set le cas par défaut pour de nombreuses locales), les textes comparés pour un usage ordinaire seront corrects (pour des détails, voyez UTN #5). Il n'y aura un problème que si les marques d'accent ne sont pas canoniques. Si cet attribut est à On, alors les meilleurs résultats sont garantis pour tous les textes. Il y a un coût de comparaison moyen si cet attribut vaut On, en fonction de la fréquence des séquences qui requièrent de la normalisation. Il n'y a pas d'effet significatif sur la taille des index de tri. Si le texte est réputé dans les formes de normalisation NFD ou NFKD, il n'y a pas besoin d'activer l'option de Normalization.

  Les valeurs possibles sont :

  - `Collator::OFF`(par défaut)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::STRENGTH` int

  Le service de collation ICU supporte de nombreux niveaux de comparaison (appelés "Levels", mais aussi connus sous le nom de "Strengths"). Avec ces catégories, ICU peut trier les chaînes avec précision, en fonction des conventions locales. Cependant, en permettant l'utilisation sélective des niveaux, la recherche d'une chaîne dans un texte peut être réalisées, à partir de différentes conditions. Pour plus d'informations, voyez le chapitre collator_set_strength().

  Les valeurs possibles sont :

  - `Collator::PRIMARY`
  - `Collator::SECONDARY`
  - `Collator::TERTIARY`(par défaut)
  - `Collator::QUATERNARY`
  - `Collator::IDENTICAL`
  - `Collator::DEFAULT_VALUE`
`Collator::HIRAGANA_QUATERNARY_MODE` int

  La compatibilité avec JIS x 4061 requiert l'introduction d'un niveau supplémentaire pour distinguer les caractères Hiragana et Katakana. Si la compatibilité avec le standard est nécessaire, alors cet attribut doit être utilisé à On, et la Strength doit prendre la valeur de Quaternary. Cela va affecter la taille des index de tri, et les performances de comparaisons des chaînes.

  Les valeurs possibles sont :

  - `Collator::OFF`(par défaut)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::NUMERIC_COLLATION` int

  Lorsqu'activé, cet attribut génère une clé de collation pour les valeurs numériques de sous-chaînes. C'est une méthode pour que '100' soit trié après '2'.

  Les valeurs possibles sont :

  - `Collator::OFF`(par défaut)
  - `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

## Historique

Version | Description
--- | ---
8.4.0 | Les constantes de classe sont désormais typées.

## Sommaire

- Collator::asort — Tri un tableau en conservant les clés, avec une collation
- Collator::compare — Compare deux chaînes Unicode
- Collator::__construct — Création d'un collator
- Collator::create — Création d'un collator
- Collator::getAttribute — Lit un attribut de collation
- Collator::getErrorCode — Lit la dernière erreur du collator
- Collator::getErrorMessage — Lit le dernier message d'erreur du collator
- Collator::getLocale — Lit le nom de la locale d'un collator
- Collator::getSortKey — Récupère la clé de tri pour une chaine
- Collator::getStrength — Récupère la dureté de classement utilisé
- Collator::setAttribute — Configure l'attribut de collation
- Collator::setStrength — Set collation strength
- Collator::sort — Trie un tableau avec une collation
- Collator::sortWithSortKeys — Tri un tableau et ses clés avec une collation