Collator

Kotlin |Java

abstract class Collator : Comparator<Any!>, Freezable<Collator!>, Cloneable

kotlin.Any
↳	android.icu.text.Collator

Known Direct Subclasses

RuleBasedCollator

RuleBasedCollator is a concrete subclass of Collator.

[icu enhancement] ICU's replacement for java.text.Collator. Methods, fields, and other functionality specific to ICU are labeled '[icu]'.

Collator performs locale-sensitive string comparison. A concrete subclass, RuleBasedCollator, allows customization of the collation ordering by the use of rule sets.

A Collator is thread-safe only when frozen. See isFrozen() and Freezable.

Following the Unicode Consortium's specifications for the Unicode Collation Algorithm (UCA), there are 5 different levels of strength used in comparisons:

PRIMARY strength: Typically, this is used to denote differences between base characters (for example, "a" < "b"). It is the strongest difference. For example, dictionaries are divided into different sections by base character.
SECONDARY strength: Accents in the characters are considered secondary differences (for example, "as" < "às" < "at"). Other differences between letters can also be considered secondary differences, depending on the language. A secondary difference is ignored when there is a primary difference anywhere in the strings.
TERTIARY strength: Upper and lower case differences in characters are distinguished at tertiary strength (for example, "ao" < "Ao" < "aò"). In addition, a variant of a letter differs from the base form on the tertiary strength (such as "A" and "Ⓐ"). Another example is the difference between large and small Kana. A tertiary difference is ignored when there is a primary or secondary difference anywhere in the strings.
QUATERNARY strength: When punctuation is ignored (see Ignoring Punctuations in the User Guide) at PRIMARY to TERTIARY strength, an additional strength level can be used to distinguish words with and without punctuation (for example, "ab" < "a-b" < "aB"). This difference is ignored when there is a PRIMARY, SECONDARY or TERTIARY difference. The QUATERNARY strength should only be used if ignoring punctuation is required.
IDENTICAL strength: When all other strengths are equal, the IDENTICAL strength is used as a tiebreaker. The Unicode code point values of the NFD form of each string are compared, just in case there is no difference. For example, Hebrew cantillation marks are only distinguished at this strength. This strength should be used sparingly, as only code point value differences between two strings is an extremely rare occurrence. Using this strength substantially decreases the performance for both comparison and collation key generation APIs. This strength also increases the size of the collation key.

Unlike the JDK, ICU4J's Collator deals only with 2 decomposition modes, the canonical decomposition mode and one that does not use any decomposition. The compatibility decomposition mode, java.text.Collator.FULL_DECOMPOSITION is not supported here. If the canonical decomposition mode is set, the Collator handles un-normalized text properly, producing the same results as if the text were normalized in NFD. If canonical decomposition is turned off, it is the user's responsibility to ensure that all text is already in the appropriate form before performing a comparison or before getting a CollationKey.

For more information about the collation service see the User Guide.

Examples of use

// 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");
  }
 
  The following example shows how to compare two strings using the
  Collator for the default locale.
 
  // Compare two strings in the default locale
  Collator myCollator = Collator.getInstance();
  myCollator.setDecomposition(NO_DECOMPOSITION);
  if (myCollator.compare("à\u0325", "a\u0325̀") != 0) {
      System.out.println("à\u0325 is not equals to a\u0325̀ without decomposition");
      myCollator.setDecomposition(CANONICAL_DECOMPOSITION);
      if (myCollator.compare("à\u0325", "a\u0325̀") != 0) {
          System.out.println("Error: à\u0325 should be equals to a\u0325̀ with decomposition");
      }
      else {
          System.out.println("à\u0325 is equals to a\u0325̀ with decomposition");
      }
  }
  else {
      System.out.println("Error: à\u0325 should be not equals to a\u0325̀ without decomposition");
  }

Summary

Nested classes
abstract	`ReorderCodes` Reordering codes for non-script groups that can be reordered under collation.

Constants
static Int	`CANONICAL_DECOMPOSITION` Decomposition mode value.
static Int	`FULL_DECOMPOSITION` [icu] Note: This is for backwards compatibility with Java APIs only.
static Int	`IDENTICAL` Smallest Collator strength value.
static Int	`NO_DECOMPOSITION` Decomposition mode value.
static Int	`PRIMARY` Strongest collator strength value.
static Int	`QUATERNARY` [icu] Fourth level collator strength value.
static Int	`SECONDARY` Second level collator strength value.
static Int	`TERTIARY` Third level collator strength value.

Protected constructors
`Collator()` Empty default constructor to make javadocs happy

Public methods
open Any	`clone()` Clones the collator.
open Collator!	`cloneAsThawed()` Provides for the clone operation.
abstract Int	`compare(source: String!, target: String!)` Compares the source text String to the target text String according to this Collator's rules, strength and decomposition mode.
open Int	`compare(source: Any!, target: Any!)` Compares the source Object to the target Object.
open Boolean	`equals(other: Any?)` Compares the equality of two Collator objects.
open Boolean	`equals(source: String!, target: String!)` Compares the equality of two text Strings using this Collator's rules, strength and decomposition mode.
open Collator!	`freeze()` Freezes the collator.
open static Array<Locale!>!	`getAvailableLocales()` Returns the set of locales, as Locale objects, for which collators are installed.
static Array<ULocale!>!	`getAvailableULocales()` [icu] Returns the set of locales, as ULocale objects, for which collators are installed.
abstract CollationKey!	`getCollationKey(source: String!)` Transforms the String into a CollationKey suitable for efficient repeated comparison.
open Int	`getDecomposition()` Returns the decomposition mode of this Collator.
open static String!	`getDisplayName(objectLocale: Locale!, displayLocale: Locale!)` [icu] Returns the name of the collator for the objectLocale, localized for the displayLocale.
open static String!	`getDisplayName(objectLocale: ULocale!, displayLocale: ULocale!)` [icu] Returns the name of the collator for the objectLocale, localized for the displayLocale.
open static String!	`getDisplayName(objectLocale: Locale!)` [icu] Returns the name of the collator for the objectLocale, localized for the default `DISPLAY` locale.
open static String!	`getDisplayName(objectLocale: ULocale!)` [icu] Returns the name of the collator for the objectLocale, localized for the default `DISPLAY` locale.
open static IntArray!	`getEquivalentReorderCodes(reorderCode: Int)` Retrieves all the reorder codes that are grouped with the given reorder code.
static ULocale!	`getFunctionalEquivalent(keyword: String!, locID: ULocale!, isAvailable: BooleanArray!)` [icu] Returns the functionally equivalent locale for the given requested locale, with respect to given keyword, for the collation service.
static ULocale!	`getFunctionalEquivalent(keyword: String!, locID: ULocale!)` [icu] Returns the functionally equivalent locale for the given requested locale, with respect to given keyword, for the collation service.
static Collator!	`getInstance()` Returns the Collator for the current default locale.
static Collator!	`getInstance(locale: ULocale!)` [icu] Returns the Collator for the desired locale.
static Collator!	`getInstance(locale: Locale!)` Returns the Collator for the desired locale.
static Array<String!>!	`getKeywordValues(keyword: String!)` [icu] Given a keyword, returns an array of all values for that keyword that are currently in use.
static Array<String!>!	`getKeywordValuesForLocale(key: String!, locale: ULocale!, commonlyUsed: Boolean)` [icu] Given a key and a locale, returns an array of string values in a preferred order that would make a difference.
static Array<String!>!	`getKeywords()` [icu] Returns an array of all possible keywords that are relevant to collation.
open Int	`getMaxVariable()` [icu] Returns the maximum reordering group whose characters are affected by the alternate handling behavior.
open IntArray!	`getReorderCodes()` Retrieves the reordering codes for this collator.
open Int	`getStrength()` Returns this Collator's strength attribute.
open UnicodeSet!	`getTailoredSet()` [icu] Returns a UnicodeSet that contains all the characters and sequences tailored in this collator.
abstract VersionInfo!	`getUCAVersion()` [icu] Returns the UCA version of this collator object.
abstract Int	`getVariableTop()` [icu] Gets the variable top value of a Collator.
abstract VersionInfo!	`getVersion()` [icu] Returns the version of this collator object.
open Int	`hashCode()` Generates a hash code for this Collator object.
open Boolean	`isFrozen()` Determines whether the object has been frozen or not.
open Unit	`setDecomposition(decomposition: Int)` Sets the decomposition mode of this Collator.
open Collator!	`setMaxVariable(group: Int)` [icu] Sets the variable top to the top of the specified reordering group.
open Unit	`setReorderCodes(vararg order: Int)` Sets the reordering codes for this collator.
open Unit	`setStrength(newStrength: Int)` Sets this Collator's strength attribute.

Inherited functions

From class Comparator

`Comparator<T>!`	`reversed()` Returns a comparator that imposes the reverse ordering of this comparator.
`Comparator<T>!`	`thenComparing(other: Comparator<in T>!)` Returns a lexicographic-order comparator with another comparator. If this `Comparator` considers two elements equal, i.e. `compare(a, b) == 0`, `other` is used to determine the order. The returned comparator is serializable if the specified comparator is also serializable.
`Comparator<T>!`	`thenComparing(keyExtractor: Function<in T, out U>!, keyComparator: Comparator<in U>!)` Returns a lexicographic-order comparator with a function that extracts a key to be compared with the given `Comparator`.
`Comparator<T>!`	`thenComparing(keyExtractor: Function<in T, out U>!)` Returns a lexicographic-order comparator with a function that extracts a `Comparable` sort key.
`Comparator<T>!`	`thenComparingDouble(keyExtractor: ToDoubleFunction<in T>!)` Returns a lexicographic-order comparator with a function that extracts a `double` sort key.
`Comparator<T>!`	`thenComparingInt(keyExtractor: ToIntFunction<in T>!)` Returns a lexicographic-order comparator with a function that extracts an `int` sort key.
`Comparator<T>!`	`thenComparingLong(keyExtractor: ToLongFunction<in T>!)` Returns a lexicographic-order comparator with a function that extracts a `long` sort key.

Parameters
`source`	String!: the source String.
`target`	String!: the target String.

Parameters
`o1`	the first object to be compared.
`o2`	the second object to be compared.
`source`	Any!: the source Object.
`target`	Any!: the target Object.

Exceptions
`java.lang.NullPointerException`	if an argument is null and this comparator does not permit null arguments
`java.lang.ClassCastException`	thrown if either arguments cannot be cast to CharSequence.

Parameters
`source`	String!: the source string to be compared.
`target`	String!: the target string to be compared.

Parameters
`objectLocale`	Locale!: the locale of the collator
`displayLocale`	Locale!: the locale for the collator's display name

Parameters
`objectLocale`	ULocale!: the locale of the collator
`displayLocale`	ULocale!: the locale for the collator's display name

Parameters
`keyword`	String!: a particular keyword as enumerated by getKeywords.
`locID`	ULocale!: The requested locale
`isAvailable`	BooleanArray!: If non-null, isAvailable[0] will receive and output boolean that indicates whether the requested locale was 'available' to the collation service. If non-null, isAvailable must have length >= 1.

Parameters
`key`	String!: one of the keys supported by this service. For now, only "collation" is supported.
`locale`	ULocale!: the locale
`commonlyUsed`	Boolean: if set to true it will return only commonly used values with the given locale in preferred order. Otherwise, it will return all the available values for the locale.

Collator

Summary

Constants

CANONICAL_DECOMPOSITION

FULL_DECOMPOSITION

IDENTICAL

NO_DECOMPOSITION

PRIMARY

QUATERNARY

SECONDARY

TERTIARY

Protected constructors

Collator

Public methods

clone

cloneAsThawed

compare

compare

equals

equals

freeze

getAvailableLocales

getAvailableULocales

getCollationKey

getDecomposition

getDisplayName

getDisplayName

getDisplayName

getDisplayName

getEquivalentReorderCodes

getFunctionalEquivalent

getFunctionalEquivalent

getInstance

getInstance

getInstance

getKeywordValues

getKeywordValuesForLocale

getKeywords

getMaxVariable

getReorderCodes

getStrength

getTailoredSet

getUCAVersion

getVariableTop

getVersion

hashCode

isFrozen

setDecomposition

setMaxVariable

setReorderCodes

setStrength