Класс Collator

java.lang.Object

java.text.Collator

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

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

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

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

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

Как и для других классов, учитывающих локаль, для получения подходящего объекта 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.

С момента версии:

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)`	Преобразует строку в последовательность битов, которую можно побитово сравнивать с другими CollationKey.
`int`	`getDecomposition()`	Получает режим декомпозиции этого Collator.
`static Collator`	`getInstance()`	Получает Collator для текущей локали по умолчанию.
`static Collator`	`getInstance(Locale desiredLocale)`	Получает Collator для указанной локали.
`int`	`getStrength()`	Возвращает свойство уровня силы этого Collator.
`abstract int`	`hashCode()`	Вычисляет хеш-код этого Collator.
`void`	`setDecomposition(int decompositionMode)`	Задает режим декомпозиции этого Collator.
`void`	`setStrength(int newStrength)`	Задает свойство уровня силы этого Collator.

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

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

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

reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

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

PRIMARY

public static final int PRIMARY

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

См. также:

SECONDARY

public static final int SECONDARY

Значение уровня силы Collator. При установке значимыми при сравнении считаются только вторичные различия и различия более высокого уровня. Соответствие уровней силы языковым особенностям зависит от локали. Типичный пример вторичного различия — акцентированные варианты одной и той же базовой буквы («a» и «ä» (U+00E9)).

См. также:

TERTIARY

public static final int TERTIARY

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

См. также:

IDENTICAL

public static final int IDENTICAL

Значение уровня силы Collator. При установке значимыми при сравнении считаются все различия. Соответствие уровней силы языковым особенностям зависит от локали. Типичный пример: управляющие символы («\u0001» и «\u0002») считаются равными на первичном, вторичном и третичном уровнях, но различными на уровне IDENTICAL. Кроме того, различия между предварительно составленными акцентированными символами, например «\u00C0» (A с грависом), и комбинируемыми акцентами, например «A\u0300» (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, так и совместимые варианты 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)

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

Параметры:

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

Возвращает:

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

См. также:

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.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/text/Collator.html