Класс Collator

java.lang.Object

java.text.Collator

Все реализуемые интерфейсы:: Cloneable, Comparator<Object>

Прямые известные подклассы:: RuleBasedCollator

public abstract class Collator extends Object implements Comparator<Object>, Cloneable

Класс Collator выполняет сравнение String с учетом локали. Этот класс используется для создания процедур поиска и сортировки текста на естественном языке.

Collator — абстрактный базовый класс. Подклассы реализуют конкретные стратегии сортировки. Один подкласс, RuleBasedCollator, входит в состав Java Platform и применим для широкого набора языков. Для более специализированных задач можно создавать другие подклассы.

Как и другие классы, учитывающие локаль, этот класс позволяет получить подходящий объект Collator для указанной локали с помощью статического фабричного метода getInstance. Изучать подклассы Collator потребуется только в том случае, если нужно разобраться в деталях конкретной стратегии сортировки или изменить ее.

В следующем примере показано, как сравнить две строки с помощью Collator для локали по умолчанию.

// Compare two strings in the default locale
Collator myCollator = Collator.getInstance();
if (myCollator.compare("abc", "ABC") < 0) {
    System.out.println("abc is less than ABC");
} else {
    System.out.println("abc is greater than or equal to ABC");
}

Чтобы определить, какие различия считаются значимыми при сравнении, можно задать свойство strength объекта Collator. Предусмотрено четыре уровня: PRIMARY, SECONDARY, TERTIARY и IDENTICAL. Точное соответствие уровней языковым особенностям зависит от локали. Например, в чешском языке «e» и «f» считаются различиями первичного уровня, «e» и «ě» — вторичного, «e» и «E» — третичного, а «e» и «e» идентичны. Ниже показано, как игнорировать регистр и диакритические знаки для американского английского.

// Get the Collator for US English and set its strength to PRIMARY
Collator usCollator = Collator.getInstance(Locale.US);
usCollator.setStrength(Collator.PRIMARY);
if (usCollator.compare("abc", "ABC") == 0) {
    System.out.println("Strings are equivalent");
}

Для однократного точного сравнения String лучше всего подходит метод compare. Однако при сортировке списка String обычно требуется сравнивать каждый String несколько раз. В этом случае CollationKey обеспечивают более высокую производительность. Класс CollationKey преобразует String в последовательность битов, которую можно сравнивать побитово с другими CollationKey. CollationKey создается объектом Collator для заданного String.

Примечание к API:

CollationKey из разных Collator сравнивать нельзя. Пример использования CollationKey см. в описании класса CollationKey.

Примечание по реализации:

При одновременном использовании RuleBasedCollator из эталонной реализации JDK, которое является подтипом, возвращаемым поставщиком по умолчанию фабричных методов getInstance(), может возникнуть значительная конкуренция потоков. Поэтому в многопоточных средах рекомендуется получать отдельный экземпляр для каждого потока.

Начиная с версии:

1.1

См. также:

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final int`	`CANONICAL_DECOMPOSITION`	Значение режима декомпозиции.
`static final int`	`FULL_DECOMPOSITION`	Значение режима декомпозиции.
`static final int`	`IDENTICAL`	Значение уровня Collator.
`static final int`	`NO_DECOMPOSITION`	Значение режима декомпозиции.
`static final int`	`PRIMARY`	Значение уровня Collator.
`static final int`	`SECONDARY`	Значение уровня Collator.
`static final int`	`TERTIARY`	Значение уровня Collator.

Краткое описание конструкторов

Collator()

Модификатор	Конструктор	Описание
`protected`	Конструктор по умолчанию.

Краткое описание методов

Модификатор и тип	Метод	Описание
`Object`	`clone()`	Переопределяет Cloneable
`int`	`compare(Object o1, Object o2)`	Сравнивает два аргумента по порядку.
`abstract int`	`compare(String source, String target)`	Сравнивает исходную строку с целевой строкой согласно правилам сортировки этого Collator.
`boolean`	`equals(Object that)`	Сравнивает два объекта Collator на равенство.
`boolean`	`equals(String source, String target)`	Удобный метод для сравнения двух строк на равенство согласно правилам сортировки этого Collator.
`static Locale[]`	`getAvailableLocales()`	Возвращает массив всех локалей, для которых методы `getInstance` этого класса могут возвращать локализованные экземпляры.
`abstract CollationKey`	`getCollationKey(String source)`	Преобразует String в последовательность битов, которую можно сравнивать побитово с другими CollationKey.
`int`	`getDecomposition()`	Возвращает режим декомпозиции этого Collator.
`static Collator`	`getInstance()`	Возвращает Collator для текущей локали по умолчанию.
`static Collator`	`getInstance(Locale desiredLocale)`	Возвращает Collator для указанной локали.
`int`	`getStrength()`	Возвращает свойство strength этого Collator.
`abstract int`	`hashCode()`	Вычисляет хеш-код этого Collator.
`void`	`setDecomposition(int decompositionMode)`	Задает режим декомпозиции этого Collator.
`void`	`setStrength(int newStrength)`	Задает свойство strength этого Collator.

Методы, объявленные в классе Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Модификатор и тип	Метод	Описание
`protected void`	`finalize()`	Устарело, подлежит удалению: этот элемент API может быть удален в будущей версии. Финализация объявлена устаревшей и подлежит удалению в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Приостанавливает текущий поток до пробуждения, обычно вследствие вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Приостанавливает текущий поток до пробуждения, обычно вследствие вызова notify или interrupt, либо до истечения заданного интервала реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Приостанавливает текущий поток до пробуждения, обычно вследствие вызова notify или interrupt, либо до истечения заданного интервала реального времени.

Методы, объявленные в интерфейсе Comparator

max, min, reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

Модификатор и тип	Метод	Описание
`default <U extends T> U`	`max(U o1, U o2)`	Возвращает большее из двух значений согласно этому компаратору.
`default <U extends T> U`	`min(U o1, U o2)`	Возвращает меньшее из двух значений согласно этому компаратору.
`default Comparator<Object>`	`reversed()`	Возвращает компаратор, задающий порядок, обратный порядку этого компаратора.
`default Comparator<Object>`	`thenComparing(Comparator<? super Object> other)`	Возвращает компаратор лексикографического порядка с другим компаратором.
`default <U extends Comparable<? super U>> Comparator<Object>`	`thenComparing(Function<? super Object, ? extends U> keyExtractor)`	Возвращает компаратор лексикографического порядка с функцией, извлекающей ключ сортировки типа `Comparable`.
`default <U> Comparator<Object>`	`thenComparing(Function<? super Object, ? extends U> keyExtractor, Comparator<? super U> keyComparator)`	Возвращает компаратор лексикографического порядка с функцией, извлекающей ключ для сравнения с заданным `Comparator`.
`default Comparator<Object>`	`thenComparingDouble(ToDoubleFunction<? super Object> keyExtractor)`	Возвращает компаратор лексикографического порядка с функцией, извлекающей ключ сортировки типа `double`.
`default Comparator<Object>`	`thenComparingInt(ToIntFunction<? super Object> keyExtractor)`	Возвращает компаратор лексикографического порядка с функцией, извлекающей ключ сортировки типа `int`.
`default Comparator<Object>`	`thenComparingLong(ToLongFunction<? super Object> keyExtractor)`	Возвращает компаратор лексикографического порядка с функцией, извлекающей ключ сортировки типа `long`.

Подробное описание полей

PRIMARY

public static final int PRIMARY

Значение силы Collator. При его установке значимыми при сравнении считаются только различия уровня PRIMARY. Отнесение языковых особенностей к уровням силы зависит от локали. Типичный пример: разные базовые буквы («a» и «b») считаются различием уровня PRIMARY.

См. также:

SECONDARY

public static final int SECONDARY

Значение силы Collator. При его установке значимыми при сравнении считаются только различия уровня SECONDARY и выше. Отнесение языковых особенностей к уровням силы зависит от локали. Типичный пример: разные варианты одной и той же базовой буквы с диакритическими знаками («a» и «ä» (U+00E4)) считаются различием уровня SECONDARY.

См. также:

TERTIARY

public static final int TERTIARY

Значение силы Collator. При его установке значимыми при сравнении считаются только различия уровня TERTIARY и выше. Отнесение языковых особенностей к уровням силы зависит от локали. Типичный пример: различия в регистре («a» и «A») считаются различием уровня TERTIARY.

См. также:

IDENTICAL

public static final int IDENTICAL

Значение силы Collator. При его установке значимыми при сравнении считаются все различия. Отнесение языковых особенностей к уровням силы зависит от локали. Типичный пример: управляющие символы («\u0001» и «\u0002») считаются одинаковыми на уровнях PRIMARY, SECONDARY и TERTIARY, но различными на уровне IDENTICAL. Кроме того, различия между предварительно составленными буквами с диакритическими знаками, например «\u00E4» (a с умлаутом), и комбинируемыми диакритическими знаками, например «a\u0308» (a с комбинируемым умлаутом), считаются значимыми на уровне IDENTICAL, если для декомпозиции задано значение NO_DECOMPOSITION.

См. также:

NO_DECOMPOSITION

public static final int NO_DECOMPOSITION

Значение режима декомпозиции. Если задано NO_DECOMPOSITION, символы с диакритическими знаками не декомпозируются при сортировке. Этот параметр обеспечивает самую быструю сортировку, но корректные результаты будут получены только для языков, в которых не используются диакритические знаки.

См. также:

CANONICAL_DECOMPOSITION

public static final int CANONICAL_DECOMPOSITION

Значение режима декомпозиции. Если задано CANONICAL_DECOMPOSITION, символы, являющиеся каноническими вариантами согласно стандарту Unicode, декомпозируются при сортировке. Этот режим следует использовать для корректной сортировки символов с диакритическими знаками.

CANONICAL_DECOMPOSITION соответствует форме нормализации D, описанной в документе дополнение № 15 к стандарту Unicode: формы нормализации Unicode.

Внешние спецификации

См. также:

FULL_DECOMPOSITION

public static final int FULL_DECOMPOSITION

Значение режима декомпозиции. Если задано FULL_DECOMPOSITION, при сортировке декомпозируются как канонические, так и совместимые варианты символов Unicode. Это позволяет сортировать не только символы с диакритическими знаками, но и символы, имеющие особые форматы, вместе с их обычными формами. Например, символы ASCII и катаканы половинной и полной ширины будут сортироваться вместе. FULL_DECOMPOSITION — наиболее полный и, следовательно, самый медленный режим декомпозиции.

FULL_DECOMPOSITION соответствует форме нормализации KD, описанной в документе дополнение № 15 к стандарту Unicode: формы нормализации Unicode.

Внешние спецификации

См. также:

Подробное описание конструкторов

Collator

protected Collator()

Конструктор по умолчанию. Этот конструктор является защищённым, чтобы подклассы могли получить к нему доступ. Обычно пользователи создают подкласс Collator, вызывая фабричный метод getInstance.

См. также:

Подробное описание методов

getInstance

public static Collator getInstance()

Возвращает Collator для текущей локали по умолчанию. Локаль по умолчанию определяется методом Locale.getDefault().

Возвращает:

Collator для локали по умолчанию (например, en_US)

См. также:

getInstance

public static Collator getInstance(Locale desiredLocale)

Возвращает Collator для заданной локали. Если для заданной локали указаны «ks» и/или «kk» параметры сортировки Unicode, этот метод вызовет setStrength(int) и/или setDecomposition(int) для созданного экземпляра, если указанные параметры сортировки Unicode распознаны согласно следующим соответствиям:

Соответствия силы и декомпозиции
Значения BCP 47 для силы (ks)	Константы Collator для силы
level1	PRIMARY
level2	SECONDARY
level3	TERTIARY^*
identic	IDENTICAL
Значения BCP 47 для нормализации (kk)	Константы Collator для декомпозиции
true	CANONICAL_DECOMPOSITION
false	NO_DECOMPOSITION^*

Звёздочкой (^*) обозначено значение по умолчанию. Если указанное значение параметра не распознано, сила и/или декомпозиция не переопределяются, как если бы в заданной локали отсутствовали параметры сортировки BCP 47.

Примечание к API:

Реализации класса Collator могут возвращать разные экземпляры в зависимости от «co» идентификатора сортировки Unicode в desiredLocale. Например:

Collator.getInstance(Locale.forLanguageTag("sv-u-co-trad"));

может вернуть экземпляр Collator с традиционным шведским порядком сортировки, в котором «v» и «w» имеют одинаковый порядок сортировки, тогда как экземпляр Collator для шведской локали без идентификатора «co» различает «v» и «w».

Параметры:

desiredLocale — желаемая локаль.

Возвращает:

Collator для заданной локали.

Внешние спецификации

См. также:

compare

public abstract int compare(String source, String target)

Сравнивает исходную строку с целевой строкой согласно правилам сортировки этого Collator. Возвращает целое число меньше, равное или больше нуля в зависимости от того, меньше, равна или больше исходная строка целевой строке. Пример использования см. в описании класса Collator.

Для однократного сравнения этот метод обеспечивает наилучшую производительность. Если заданная строка будет участвовать в нескольких сравнениях, CollationKey.compareTo обеспечит наилучшую производительность. Пример использования CollationKey см. в описании класса Collator.

Параметры:

source — исходная строка.

target — целевая строка.

Возвращает:

Целое число. Значение меньше нуля, если исходная строка меньше целевой; равно нулю, если строки равны; больше нуля, если исходная строка больше целевой.

См. также:

compare

public int compare(Object o1, Object o2)

Сравнивает два аргумента по порядку. Возвращает отрицательное целое число, ноль или положительное целое число в зависимости от того, меньше, равен или больше первый аргумент второго.

Эта реализация просто возвращает compare((String)o1, (String)o2) .

Определено в:

compare в интерфейсе Comparator<Object>

Параметры:

o1 — первый сравниваемый объект.

o2 — второй сравниваемый объект.

Возвращает:

Отрицательное целое число, ноль или положительное целое число в зависимости от того, меньше, равен или больше первый аргумент второго.

Выбрасывает:

ClassCastException — аргументы нельзя привести к типу String.

Начиная с версии:

1.2

См. также:

getCollationKey

public abstract CollationKey getCollationKey(String source)

Преобразует строку в последовательность битов, которую можно побитово сравнивать с другими ключами сортировки. Ключи сортировки обеспечивают более высокую производительность, чем Collator.compare, если строки участвуют в нескольких сравнениях. Пример использования ключей сортировки см. в описании класса Collator.

Параметры:

source — строка, которую необходимо преобразовать в ключ сортировки.

Возвращает:

Ключ сортировки для заданной строки, сформированный согласно правилам сортировки этого Collator. Если исходная строка равна null, возвращается null.

См. также:

equals

public boolean equals(String source, String target)

Вспомогательный метод для сравнения двух строк на равенство согласно правилам сортировки этого Collator.

Параметры:

source — исходная строка для сравнения.

target — целевая строка для сравнения.

Возвращает:

true, если строки равны согласно правилам сортировки; в противном случае — false.

См. также:

getStrength

public int getStrength()

Возвращает свойство силы этого Collator. Свойство силы определяет минимальный уровень различий, считающихся значимыми при сравнении. Пример использования см. в описании класса Collator.

Возвращает:

текущее значение свойства силы этого Collator.

См. также:

setStrength

public void setStrength(int newStrength)

Задаёт свойство силы этого Collator. Свойство силы определяет минимальный уровень различий, считающихся значимыми при сравнении. Пример использования см. в описании класса Collator.

Параметры:

newStrength — новое значение силы.

Выбрасывает:

IllegalArgumentException — если новое значение силы не равно PRIMARY, SECONDARY, TERTIARY или IDENTICAL.

См. также:

getDecomposition

public int getDecomposition()

Возвращает режим декомпозиции этого Collator. Режим декомпозиции определяет обработку составных символов Unicode. Изменение режима декомпозиции позволяет пользователю выбирать между более высокой скоростью и более полной сортировкой.

Доступны три значения режима декомпозиции:

NO_DECOMPOSITION,
CANONICAL_DECOMPOSITION
FULL_DECOMPOSITION.

Описание значений см. в документации к соответствующим константам.

Возвращает:

режим декомпозиции

См. также:

setDecomposition

public void setDecomposition(int decompositionMode)

Задаёт режим декомпозиции этого Collator. Описание режима декомпозиции см. в методе getDecomposition.

Параметры:

decompositionMode — новый режим декомпозиции.

Выбрасывает:

IllegalArgumentException — если задано недопустимое значение режима декомпозиции.

См. также:

getAvailableLocales

public static Locale[] getAvailableLocales()

Возвращает массив всех локалей, для которых методы getInstance этого класса могут возвращать локализованные экземпляры. Возвращаемый массив представляет собой объединение локалей, поддерживаемых средой выполнения Java и установленными реализациями CollatorProvider. Как минимум, возвращаемый массив должен содержать экземпляр Locale, равный Locale.ROOT, и экземпляр Locale, равный Locale.US.

Возвращает:: Массив локалей, для которых доступны локализованные экземпляры Collator.

clone

public Object clone()

Переопределяет Cloneable

Переопределяет:

clone в классе Object

Возвращает:

копию этого экземпляра.

См. также:

equals

public boolean equals(Object that)

Сравнивает два объекта Collator на равенство.

Определено в:

equals в интерфейсе Comparator<Object>

Переопределяет:

equals в классе Object

Параметры:

that — Collator для сравнения с этим экземпляром.

Возвращает:

true, если этот Collator совпадает с тем Collator; в противном случае — false.

См. также:

hashCode

public abstract int hashCode()

Вычисляет хеш-код этого Collator.

Переопределяет:

hashCode в классе Object

Возвращает:

значение хеш-кода для этого объекта

См. также:

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.