Skip to content

Most visited

Recently visited

navigation
Added in API level 1

Collator

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

java.lang.Object
   ↳ java.text.Collator
Known Direct Subclasses


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

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

This Collator deals only with two 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, 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.

Examples:

 // 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(Collator.NO_DECOMPOSITION);
 if (myCollator.compare("ḁ̀", "ḁ̀") != 0) {
     System.out.println("ḁ̀ is not equal to ḁ̀ without decomposition");
     myCollator.setDecomposition(Collator.CANONICAL_DECOMPOSITION);
     if (myCollator.compare("ḁ̀", "ḁ̀") != 0) {
         System.out.println("Error: ḁ̀ should be equal to ḁ̀ with decomposition");
     } else {
         System.out.println("ḁ̀ is equal to ḁ̀ with decomposition");
     }
 } else {
     System.out.println("Error: ḁ̀ should be not equal to ḁ̀ without decomposition");
 }
 

See also:

Summary

Constants

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.

Protected constructors

Collator()

Constructs a new Collator instance.

Public methods

Object clone()

Returns a new collator with the same decomposition mode and strength value as this collator.

abstract int compare(String string1, String string2)

Compares two strings to determine their relative order.

int compare(Object object1, Object object2)

Compares two objects to determine their relative order.

boolean equals(Object object)

Compares this collator with the specified object and indicates if they are equal.

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.

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.

int getStrength()

Returns the strength value for this collator.

abstract int hashCode()

Returns an integer hash code for this object.

void setDecomposition(int value)

Sets the decomposition rule for this collator.

void setStrength(int value)

Sets the strength value for this collator.

Inherited methods

From class java.lang.Object
From interface java.util.Comparator

Constants

CANONICAL_DECOMPOSITION

Added in API level 1
int CANONICAL_DECOMPOSITION

Constant used to specify the decomposition rule.

Constant Value: 1 (0x00000001)

FULL_DECOMPOSITION

Added in API level 1
int FULL_DECOMPOSITION

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

Constant Value: 2 (0x00000002)

IDENTICAL

Added in API level 1
int IDENTICAL

Constant used to specify the collation strength.

Constant Value: 3 (0x00000003)

NO_DECOMPOSITION

Added in API level 1
int NO_DECOMPOSITION

Constant used to specify the decomposition rule.

Constant Value: 0 (0x00000000)

PRIMARY

Added in API level 1
int PRIMARY

Constant used to specify the collation strength.

Constant Value: 0 (0x00000000)

SECONDARY

Added in API level 1
int SECONDARY

Constant used to specify the collation strength.

Constant Value: 1 (0x00000001)

TERTIARY

Added in API level 1
int TERTIARY

Constant used to specify the collation strength.

Constant Value: 2 (0x00000002)

Protected constructors

Collator

Added in API level 1
Collator ()

Constructs a new Collator instance.

Public methods

clone

Added in API level 1
Object clone ()

Returns a new collator with the same decomposition mode and strength value as this collator.

Returns
Object a shallow copy of this collator.

See also:

compare

Added in API level 1
int compare (String string1, 
                String string2)

Compares two strings to determine their relative order.

Parameters
string1 String: the first string to compare.
string2 String: the second string to compare.
Returns
int a negative value if string1 is less than string2, 0 if they are equal and a positive value if string1 is greater than string2.

compare

Added in API level 1
int compare (Object object1, 
                Object object2)

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

Parameters
object1 Object: the first string to compare.
object2 Object: the second string to compare.
Returns
int 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.

equals

Added in API level 1
boolean equals (Object object)

Compares this collator with the specified object and indicates if they are equal.

Parameters
object Object: the object to compare with this object.
Returns
boolean true if object is a Collator object and it has the same strength and decomposition values as this collator; false otherwise.

See also:

equals

Added in API level 1
boolean equals (String string1, 
                String string2)

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

Parameters
string1 String: the first string to compare.
string2 String: the second string to compare.
Returns
boolean true if string1 and string2 are equal using the collation rules, false otherwise.

getAvailableLocales

Added in API level 1
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.

Returns
Locale[]

getCollationKey

Added in API level 1
CollationKey getCollationKey (String string)

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

Parameters
string String: the source string that is converted into a collation key.
Returns
CollationKey the collation key for string.

getDecomposition

Added in API level 1
int getDecomposition ()

Returns the decomposition rule for this collator.

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

getInstance

Added in API level 1
Collator getInstance ()

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

Returns
Collator

getInstance

Added in API level 1
Collator getInstance (Locale locale)

Returns a Collator instance which is appropriate for locale.

Parameters
locale Locale
Returns
Collator

getStrength

Added in API level 1
int getStrength ()

Returns the strength value for this collator.

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

hashCode

Added in API level 1
int hashCode ()

Returns an integer hash code for this object. By contract, any two objects for which equals(Object) returns true must return the same hash code value. This means that subclasses of Object usually override both methods or neither method.

Note that hash values must not change over time unless information used in equals comparisons also changes.

See Writing a correct hashCode method if you intend implementing your own hashCode method.

Returns
int this object's hash code.

setDecomposition

Added in API level 1
void setDecomposition (int value)

Sets the decomposition rule for this collator.

Parameters
value int: 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.

setStrength

Added in API level 1
void setStrength (int value)

Sets the strength value for this collator.

Parameters
value int: the strength value, either PRIMARY, SECONDARY, TERTIARY, or IDENTICAL.
Throws
IllegalArgumentException if the provided strength value is not valid.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.