Module java.base

Package java.text

Class Collator

✗

public abstract class Collator

extends java.lang.Object

implements java.lang.Cloneable, java.util.Comparator<java.lang.Object>

Comparing jdk-20-ga and jdk-21+35

All Implemented Interfaces:: Cloneable , Comparator<Object>

Direct Known Subclasses:: RuleBasedCollator

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.

Moved out of a quote.Moved out of a preformatted block.Moved out of a computer code block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.// Compare two strings in the default locale

Moved out of a quote.Moved out of a preformatted block.Moved out of a computer code block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.Collator myCollator = Collator.getInstance();
ifMoved out of a quote.Moved out of a preformatted block.Moved out of a computer code block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.

Moved out of a quote.Moved out of a preformatted block.Moved out of a computer code block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.(

Moved out of a quote.Moved out of a preformatted block.Moved out of a computer code block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.myCollator.compare("abc", "ABC") < 0

Moved out of a quote.Moved out of a preformatted block.Moved out of a computer code block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.) {Moved out of a quote.Moved out of a preformatted block.Moved out of a computer code block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.
    System.out.println("abc is less than ABC");
}Moved out of a quote.Moved out of a preformatted block.Moved out of a computer code block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java. else {Moved out of a quote.Moved out of a preformatted block.Moved out of a computer code block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.
    System.out.println("abc is greater than or equal to ABC");
}Moved out of a quote.Moved out of a preformatted block.Moved out of a computer code block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.

Moved out of a quote.Moved out of a preformatted block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.

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 dependent. 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.

Moved out of a quote.Moved out of a preformatted block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.// Moved out of a quote.Moved out of a preformatted block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.Get the Collator for US English and set its strength to PRIMARY

Moved out of a quote.Moved out of a preformatted block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.Collator usCollator = Collator.getInstance(Locale.US);

Moved out of a quote.Moved out of a preformatted block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.usCollator.setStrength(Collator.PRIMARY);
ifMoved out of a quote.Moved out of a preformatted block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.

Moved out of a quote.Moved out of a preformatted block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.(

Moved out of a quote.Moved out of a preformatted block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.usCollator.compare("abc", "ABC") == 0

Moved out of a quote.Moved out of a preformatted block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.) {

Moved out of a quote.Moved out of a preformatted block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.System.out.println("Strings are equivalent");

Moved out of a quote.Moved out of a preformatted block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.Moved to a computer code block with class language-java.}

Moved out of a quote.Moved out of a preformatted block.Moved to a division with class snippet-container.Moved to a preformatted block with class snippet.

For comparing String s exactly once, the compare method provides the best performance. When sorting a list of String s however, it is generally necessary to compare each String multiple times. In this case, CollationKey s provide better performance. The CollationKey class converts a String to a series of bits that can be compared bitwise against other CollationKey s. A CollationKey is created by a Collator object for a given String .

API Moved out of a division with class block.Moved out of a paragraph.Strong style removed.Moved to a definition list with class notes.Moved to a definition term.Note:: Moved out of a division with class block.Moved out of a paragraph.Moved to a definition list with class notes.Moved to a definition.CollationKey Moved out of a division with class block.Moved out of a paragraph.Moved to a definition list with class notes.Moved to a definition.s from different Moved out of a division with class block.Moved out of a paragraph.Moved to a definition list with class notes.Moved to a definition.Collator Moved out of a division with class block.Moved out of a paragraph.Moved to a definition list with class notes.Moved to a definition.s can not be compared. See the class description for Moved out of a division with class block.Moved out of a paragraph.Moved to a definition list with class notes.Moved to a definition.CollationKey Moved out of a division with class block.Moved out of a paragraph.Moved to a definition list with class notes.Moved to a definition. for an example using Moved out of a division with class block.Moved out of a paragraph.Moved to a definition list with class notes.Moved to a definition.CollationKey Moved out of a division with class block.Moved out of a paragraph.Moved to a definition list with class notes.Moved to a definition.s.

Since:

1.1

See Also:

Fields

✗
public static final int CANONICAL_DECOMPOSITION = 1
Comparing jdk-20-ga and jdk-21+35
CANONICAL_DECOMPOSITION

public static final int CANONICAL_DECOMPOSITION

Decomposition mode value. With CANONICAL_DECOMPOSITION set, characters that are canonical variants according to Unicode standard will be decomposed for collation. This should be used to get correct collation of accented characters.
CANONICAL_DECOMPOSITION corresponds to Normalization Form D as described in Unicode Standard Annex #15: Unicode Normalization Forms.

External Specifications

Unicode Normalization Forms

See Also:

getDecomposition()
setDecomposition(int)
Constant Field Values
✗
public static final int FULL_DECOMPOSITION = 2
Comparing jdk-20-ga and jdk-21+35
FULL_DECOMPOSITION

public static final int FULL_DECOMPOSITION

Decomposition mode value. With FULL_DECOMPOSITION set, both Unicode canonical variants and Unicode compatibility variants will be decomposed for collation. This causes not only accented characters to be collated, but also characters that have special formats to be collated with their norminal form. For example, the half-width and full-width ASCII and Katakana characters are then collated together. FULL_DECOMPOSITION is the most complete and therefore the slowest decomposition mode.
FULL_DECOMPOSITION corresponds to Normalization Form KD as described in Unicode Standard Annex #15: Unicode Normalization Forms.

External Specifications

Unicode Normalization Forms

See Also:

getDecomposition()
setDecomposition(int)
Constant Field Values
✓
public static final int IDENTICAL = 3
✗
public static final int NO_DECOMPOSITION = 0
Comparing jdk-20-ga and jdk-21+35
NO_DECOMPOSITION

public static final int NO_DECOMPOSITION

Decomposition mode value. With NO_DECOMPOSITION set, accented characters will not be decomposed for collation. This is the default setting and provides the fastest collation but will only produce correct results for languages that do not use accents.

See Also:

getDecomposition()
setDecomposition(int)
Constant Field Values
✓
public static final int PRIMARY = 0
✓
public static final int SECONDARY = 1
✓
public static final int TERTIARY = 2

Constructors

✓
protected Collator()

Methods

✓
public java.lang.Object clone()
✓
public int compare(java.lang.Object arg0, java.lang.Object arg1)
✓
public abstract int compare(java.lang.String arg0, java.lang.String arg1)
✓
public boolean equals(java.lang.Object arg0)
✓
public boolean equals(java.lang.String arg0, java.lang.String arg1)
✓
public static java.util.Locale[] getAvailableLocales()
✓
public abstract java.text.CollationKey getCollationKey(java.lang.String arg0)
✓
public int getDecomposition()
✓
public static java.text.Collator getInstance()

✗

public static java.text.Collator getInstance(java.util.Locale arg0)

Comparing jdk-20-ga and jdk-21+35

getInstance

public static Collator getInstance (Locale desiredLocale)

Gets the Collator for the desired locale. If the desired locale has the "ks " and/or the "kk " Unicode collation settings, this method will call setStrength(int) and/or setDecomposition(int) on the created instance, if the specified Unicode collation settings are recognized based on the following mappings:

Strength/Decomposition mappings
BCP 47 values for strength (ks)	Collator constants for strength
level1	PRIMARY
level2	SECONDARY
level3	TERTIARY^*
identic	IDENTICAL
BCP 47 values for normalization (kk)	Collator constants for decomposition
true	CANONICAL_DECOMPOSITION
false	NO_DECOMPOSITION^*

Asterisk (^* ) denotes the default value. If the specified setting value is not recognized, the strength and/or decomposition is not overridden, as if there were no BCP 47 collation options in the desired locale.

API Note:

Implementations of Collator class may produce different instances based on the "co " Unicode collation identifier in the desiredLocale . For example:

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

may return a Collator instance with the Swedish traditional sorting, which gives 'v' and 'w' the same sorting order, while the Collator instance for the Swedish locale without "co" identifier distinguishes 'v' and 'w'.

Parameters:

desiredLocale - the desired locale.

Returns:

the Collator for the desired locale.

External Specifications

See Also:

✓
public int getStrength()
✓
public abstract int hashCode()
✓
public void setDecomposition(int arg0)
✓
public void setStrength(int arg0)

Summary

Differences
	Added	Added	Added	Changed	Removed	Total
	Elements	Comments	Descriptions			Total
Collator			1	1	14	16
getInstance(Locale)			9			9
CANONICAL_DECOMPOSITION			1			1
FULL_DECOMPOSITION			1			1
NO_DECOMPOSITION					2	2
Total			12	1	16	29

Class Collator

Fields

CANONICAL_DECOMPOSITION

FULL_DECOMPOSITION

NO_DECOMPOSITION

Constructors

Methods

getInstance

Summary