# Класс Collator

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

## Введение

Сравнивает строки с поддержкой порядка сортировки с учётом региональных настроек.

## Обзор класса

class Collator {
/* Константы */
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;
/* Методы */
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
}

## Предопределённые константы

`Collator::FRENCH_COLLATION` int

  Сортировка строк с различными акцентами с конца строки. Этот атрибут автоматически устанавливается в On для французской и некоторых других локалей. Обычно пользователям нет необходимости специально задавать этот параметр. Существуют издержки производительности при сравнении строк, если этот параметр установлен как On, но это никак не влияет на длину ключа сортировки. Возможные значения:

  - `Collator::ON`
  - `Collator::OFF`(по умолчанию)
  - `Collator::DEFAULT_VALUE`

  Пример #1 Правила FRENCH_COLLATION

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

  Атрибут "Alternate" используется для контроля обработки так называемых "переменных символов" в UCA: пробелы, знаки пунктуации и символы. Если "Alternate" установлен как NonIgnorable (N), то различия в этих символах будут считаться такими же значимыми, как и различия между буквами. Если "Alternate" установлен как Shifted (S), то эти символы будут иметь низкую значимость. Значение Shifted зачастую используется в комбинации с Strength, установленным в "Quaternary". В таких случаях подобные символы будут учитываться при сортировке, но только если все остальные аспекты строк (буквы, акценты, регистр) идентичны. Если "Alternate" не установлен как "Shifted", то разницы между уровнями "Strength" 3 и 4 не будет. Более подробно и с примерами читайте в разделе "Variable_Weighting" на сайте » UCA. Причина, по которой значения для "Alternate" — это не просто On и Off, заключается в том, что в будущем могут быть добавлены дополнительные варианты. Опция UCA "Blanked" выражается с помощью "Strength", установленного в 3, и "Alternate", установленного в "Shifted". Для большинства локалей этот параметр по умолчанию равен "NonIgnorable". Если задано "Shifted", то обработка может быть медленнее в случае, если у вас много строк, отличающихся только пунктуацией. Длина ключа сортировки не затрагивается, только если также не увеличивался уровень "Strength".

  Возможные значения:

  - `Collator::NON_IGNORABLE`(по умолчанию)
  - `Collator::SHIFTED`
  - `Collator::DEFAULT_VALUE`

  Пример #2 ALTERNATE_HANDLING rules

  - 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

  Атрибут "Case_First" используется для определения порядка сортировки в зависимости от регистра символов при отсутствии других различий в строках. Возможные значения: Uppercase_First(U), Lowercase_First (L), Default и Off. Между "Off" и "Lowercase_First" практически нет разницы, так что пользователи обычно не используют "Lowercase_First", а только Off или Uppercase_First. (Те, кому действительно интересна разница между X и L могут обратиться к `Настройке Collation`). Задание L или U не сказывается на скорости сравнения, но влияет на длину ключа сортировки.

  Возможные значения:

  - `Collator::OFF`(по умолчанию)
  - `Collator::LOWER_FIRST`
  - `Collator::UPPER_FIRST`
  - `Collator:DEFAULT`

  Пример #3 Правила CASE_FIRST

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

  Атрибут "Case_Level" используется, когда акценты не важны, а регистр важен. В таких случаях установите "Strength" в значение Primary, и "Case_Level" в On. В большинстве локалей по умолчанию задано значение "Off". Оказывает незначительное влияние на скорость сравнения и длину ключа сортировки, если установлено как On.

  Возможные значения:

  - `Collator::OFF`(по умолчанию)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`

  Пример #4 CASE_LEVEL rules

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

  Настройка "Normalization" определяет, будет ли текст тщательно нормализован в сравнении или нет. Даже если данная настройка отключена (по умолчанию для многих локалей), текст в общем случае будет сравниваться корректно (подробности в UTN #5). Проблемы могут быть только с отметками акцентов, расположенными в неканоничном порядке. Если установлено как On, то будет гарантирован наилучший результат для всех возможных вариантов текста. Однако, если установлено значение On, это скажется на скорости сравнения в зависимости от количества последовательностей, которые необходимо нормализовать. Какого-либо заметного влияния на длину ключа сортировки оказано не будет. Если заранее известно, что текст уже нормализован как NFD или NFKD, необходимости в использовании этой настройки нет.

  Возможные значения:

  - `Collator::OFF`(по умолчанию)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::STRENGTH` int

  ICU Collation Service поддерживает множество уровней сравнения (они называются "Levels", но также известны как "Strengths"). Использование этих настроек позволяет ICU сортировать строки точно в соответствии с правилами локали. Однако, разрешая выборочное использование этих уровней, поиск строки в тексте можно производить с использованием различных условий. Больше информации описано в главе, посвящённой collator_set_strength().

  Возможные значения:

  - `Collator::PRIMARY`
  - `Collator::SECONDARY`
  - `Collator::TERTIARY`(по умолчанию)
  - `Collator::QUATERNARY`
  - `Collator::IDENTICAL`
  - `Collator::DEFAULT_VALUE`
`Collator::HIRAGANA_QUATERNARY_MODE` int

  Совместимость с JIS x 4061 требует введения дополнительного уровня для выделения символов Hiragana и Katakana. Если требуется совместимость со стандартом, то этот атрибут потребуется задать как On, а "Strength" как "Quaternary". Это скажется на длине ключа сортировки и скорости сравнения.

  Возможные значения:

  - `Collator::OFF`(по умолчанию)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::NUMERIC_COLLATION` int

  Если включён, этот атрибут генерирует ключ сравнения для числового значения подстроки, состоящей из цифр. Это позволяет при сортировке помещать '100' после '2'.

  Возможные значения:

  - `Collator::OFF`(по умолчанию)
  - `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

## Список изменений

Версия | Описание
--- | ---
8.4.0 | Константы класса стали типизированными.

## Содержание

- Collator::asort — Сортирует массив с сохранением ассоциации индекса
- Collator::compare — Сравнивает две строки Unicode
- Collator::__construct — Создаёт новый экземпляр Collator
- Collator::create — Создаёт новый экземпляр Collator
- Collator::getAttribute — Получает значение атрибута сопоставления
- Collator::getErrorCode — Получает последний код ошибки Collator
- Collator::getErrorMessage — Получает текст для кода последней ошибки Collator
- Collator::getLocale — Получает название локали для Collator
- Collator::getSortKey — Получает ключ сортировки строки
- Collator::getStrength — Получает текущую силу сопоставления
- Collator::setAttribute — Устанавливает атрибут сопоставления
- Collator::setStrength — Устанавливает силу сопоставления
- Collator::sort — Сортирует массив с использованием указанного средства сортировки
- Collator::sortWithSortKeys — Сортирует массив с использованием указанного Collator и ключей сортировки

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