Collator

AI-generated Key Takeaways

• The Collator class enables language-sensitive string comparisons for sorting and searching, adapting to specific languages and offering different comparison sensitivities.

• It provides methods for creating Collator instances, comparing strings, generating collation keys for efficient comparisons, and controlling comparison behavior.

• CollationKey objects facilitate efficient repeated comparisons by representing strings as comparable bit sequences but are not interchangeable between different Collator instances.

• Developers should be aware of locale considerations, especially the default locale, and limitations like the unsupported FULL_DECOMPOSITION rule.

• RuleBasedCollator, CollationKey, and CollationElementIterator offer more advanced collation functionalities for complex scenarios.

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

The Collator class performs locale-sensitive String comparison. You use this class to build searching and sorting routines for natural language text.

Collator is an abstract base class. Subclasses implement specific collation strategies. One subclass, RuleBasedCollator, is currently provided with the Java Platform and is applicable to a wide set of languages. Other subclasses may be created to handle more specialized needs.

Like other locale-sensitive classes, you can use the static factory method, getInstance, to obtain the appropriate Collator object for a given locale. You will only need to look at the subclasses of Collator if you need to understand the details of a particular collation strategy or if you need to modify that strategy.

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();
 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");
 

You can set a Collator's strength property to determine the level of difference considered significant in comparisons. Four strengths are provided: PRIMARY, SECONDARY, TERTIARY, and IDENTICAL. The exact assignment of strengths to language features is locale dependant. For example, in Czech, "e" and "f" are considered primary differences, while "e" and "ě" are secondary differences, "e" and "E" are tertiary differences and "e" and "e" are identical. The following shows how both case and accents could be ignored for US English.

 //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");
 }
 

For comparing Strings exactly once, the compare method provides the best performance. When sorting a list of Strings however, it is generally necessary to compare each String multiple times. In this case, CollationKeys provide better performance. The CollationKey class converts a String to a series of bits that can be compared bitwise against other CollationKeys. A CollationKey is created by a Collator object for a given String.
Note: CollationKeys from different Collators can not be compared. See the class description for CollationKey for an example using CollationKeys.

See Also

• ERROR(/RuleBasedCollator)
• CollationKey
• ERROR(/CollationElementIterator)
• Locale

Constant Summary

int	CANONICAL_DECOMPOSITION	Constant used to specify the decomposition rule.
int	FULL_DECOMPOSITION	Constant used to specify the decomposition rule.
int	IDENTICAL	Constant used to specify the collation strength.
int	NO_DECOMPOSITION	Constant used to specify the decomposition rule.
int	PRIMARY	Constant used to specify the collation strength.
int	SECONDARY	Constant used to specify the collation strength.
int	TERTIARY	Constant used to specify the collation strength.

Public Constructor Summary

Collator()

Public Method Summary

Object	clone() Creates and returns a copy of this Object.
int	compare(Object object1, Object object2) Compares two objects to determine their relative order.
abstract int	compare(String string1, String string2) Compares two strings to determine their relative order.
boolean	equals(String string1, String string2) Compares two strings using the collation rules to determine if they are equal.
static Locale[]	getAvailableLocales() Returns an array of locales for which custom Collator instances are available.
abstract CollationKey	getCollationKey(String string) Returns a CollationKey for the specified string for this collator with the current decomposition rule and strength value.
abstract int	getDecomposition() Returns the decomposition rule for this collator.
static Collator	getInstance() Returns a Collator instance which is appropriate for the user's default Locale.
static Collator	getInstance(Locale locale) Returns a Collator instance which is appropriate for locale.
abstract int	getStrength() Returns the strength value for this collator.
abstract void	setDecomposition(int value) Sets the decomposition rule for this collator.
abstract void	setStrength(int value) Sets the strength value for this collator.

Inherited Method Summary

From class java.lang.Object

Object	clone() Creates and returns a copy of this Object.
boolean	equals(Object obj) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of Class that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait(long timeout, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait(long timeout) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object.

From interface java.util.Comparator

abstract int	compare(Object o1, Object o2) Compares its two arguments for order.
static <T, U> Comparator<Object>	comparing(Function<? super T, ? extends U> keyExtractor, Comparator<? super U> keyComparator) Accepts a function that extracts a sort key from a type T, and returns a Comparator<T> that compares by that sort key using the specified Comparator.
static <T, U extends Comparable<? super U>> Comparator<Object>	comparing(Function<? super T, ? extends U> keyExtractor) Accepts a function that extracts a Comparable sort key from a type T, and returns a Comparator<T> that compares by that sort key.
static <T> Comparator<Object>	comparingDouble(ToDoubleFunction<? super T> keyExtractor) Accepts a function that extracts a double sort key from a type T, and returns a Comparator<T> that compares by that sort key.
static <T> Comparator<Object>	comparingInt(ToIntFunction<? super T> keyExtractor) Accepts a function that extracts an int sort key from a type T, and returns a Comparator<T> that compares by that sort key.
static <T> Comparator<Object>	comparingLong(ToLongFunction<? super T> keyExtractor) Accepts a function that extracts a long sort key from a type T, and returns a Comparator<T> that compares by that sort key.
abstract boolean	equals(Object obj) Indicates whether some other object is "equal to" this comparator.
static <T extends Comparable<? super T>> Comparator<T>	naturalOrder() Returns a comparator that compares Comparable objects in natural order.
static <T> Comparator<Object>	nullsFirst(Comparator<? super T> comparator) Returns a null-friendly comparator that considers null to be less than non-null.
static <T> Comparator<Object>	nullsLast(Comparator<? super T> comparator) Returns a null-friendly comparator that considers null to be greater than non-null.
static <T extends Comparable<? super T>> Comparator<T>	reverseOrder() Returns a comparator that imposes the reverse of the natural ordering.
Comparator<Object>	reversed() Returns a comparator that imposes the reverse ordering of this comparator.
<U extends Comparable<? super U>> Comparator<Object>	thenComparing(Function<? super T, ? extends U> keyExtractor) Returns a lexicographic-order comparator with a function that extracts a Comparable sort key.
<U> Comparator<Object>	thenComparing(Function<? super T, ? extends U> keyExtractor, Comparator<? super U> keyComparator) Returns a lexicographic-order comparator with a function that extracts a key to be compared with the given Comparator.
Comparator<Object>	thenComparing(Comparator<? super T> other) Returns a lexicographic-order comparator with another comparator.
Comparator<Object>	thenComparingDouble(ToDoubleFunction<? super T> keyExtractor) Returns a lexicographic-order comparator with a function that extracts a double sort key.
Comparator<Object>	thenComparingInt(ToIntFunction<? super T> keyExtractor) Returns a lexicographic-order comparator with a function that extracts a int sort key.
Comparator<Object>	thenComparingLong(ToLongFunction<? super T> keyExtractor) Returns a lexicographic-order comparator with a function that extracts a long sort key.

Constants

public static final int CANONICAL_DECOMPOSITION

Constant used to specify the decomposition rule.

Constant Value: 1

public static final int FULL_DECOMPOSITION

Constant used to specify the decomposition rule. This value for decomposition is not supported.

Constant Value: 2

public static final int IDENTICAL

Constant used to specify the collation strength.

Constant Value: 3

public static final int NO_DECOMPOSITION

Constant used to specify the decomposition rule.

Constant Value: 0

public static final int PRIMARY

Constant used to specify the collation strength.

Constant Value: 0

public static final int SECONDARY

Constant used to specify the collation strength.

Constant Value: 1

public static final int TERTIARY

Constant used to specify the collation strength.

Constant Value: 2

Public Constructors

public Collator ()

Public Methods

public Object clone ()

Creates and returns a copy of this Object. The default implementation returns a so-called "shallow" copy: It creates a new instance of the same class and then copies the field values (including object references) from this instance to the new instance. A "deep" copy, in contrast, would also recursively clone nested objects. A subclass that needs to implement this kind of cloning should call super.clone() to create the new instance and then create deep copies of the nested, mutable objects.

Returns

• a copy of this object.

public int compare (Object object1, Object object2)

Compares two objects to determine their relative order. The objects must be strings.

Parameters

object1	the first string to compare.
object2	the second string to compare.

Returns

• a negative value if object1 is less than object2, 0 if they are equal, and a positive value if object1 is greater than object2.

Throws

ClassCastException	if object1 or object2 is not a String.

public abstract int compare (String string1, String string2)

Compares two strings to determine their relative order.

Parameters

string1	the first string to compare.
string2	the second string to compare.

Returns

• a negative value if string1 is less than string2, 0 if they are equal and a positive value if string1 is greater than string2.

public boolean equals (String string1, String string2)

Compares two strings using the collation rules to determine if they are equal.

Parameters

string1	the first string to compare.
string2	the second string to compare.

Returns

• true if string1 and string2 are equal using the collation rules, false otherwise.

public static Locale[] getAvailableLocales ()

Returns an array of locales for which custom Collator instances are available.

Note that Android does not support user-supplied locale service providers.

public abstract CollationKey getCollationKey (String string)

Returns a CollationKey for the specified string for this collator with the current decomposition rule and strength value.

Parameters

string	the source string that is converted into a collation key.

Returns

• the collation key for string.

public abstract int getDecomposition ()

Returns the decomposition rule for this collator.

Returns

• the decomposition rule, either NO_DECOMPOSITION or CANONICAL_DECOMPOSITION. FULL_DECOMPOSITION is not supported.

public static Collator getInstance ()

Returns a Collator instance which is appropriate for the user's default Locale. See "Be wary of the default locale".

public static Collator getInstance (Locale locale)

Returns a Collator instance which is appropriate for locale.

Parameters

locale

public abstract int getStrength ()

Returns the strength value for this collator.

Returns

• the strength value, either PRIMARY, SECONDARY, TERTIARY or IDENTICAL.

public abstract void setDecomposition (int value)

Sets the decomposition rule for this collator.

Parameters

value	the decomposition rule, either NO_DECOMPOSITION or CANONICAL_DECOMPOSITION. FULL_DECOMPOSITION is not supported.

Throws

IllegalArgumentException	if the provided decomposition rule is not valid. This includes FULL_DECOMPOSITION.

public abstract void setStrength (int value)

Sets the strength value for this collator.

Parameters

value	the strength value, either PRIMARY, SECONDARY, TERTIARY, or IDENTICAL.

Throws

IllegalArgumentException	if the provided strength value is not valid.