Chapter 16
The java.text Package

Collator

Name

Collator

Synopsis

Class Name:

java.text.Collator

Superclass:

java.lang.Object

Immediate Subclasses:

java.text.RuleBasedCollator

Interfaces Implemented:

java.lang.Cloneable, java.io.Serializable

Availability:

New as of JDK 1.1

The Collator class compares strings in a manner that is appropriate for a particular locale. Although Collator is an abstract class, the getInstance() factory methods can be used to get a usable instance of a Collator subclass that implements a particular collation strategy. One subclass, RuleBasedCollator, is provided as part of the JDK.

A Collator object has a strength property that controls the level of difference that is considered significant for comparison purposes. The Collator class provides four strength values: PRIMARY, SECONDARY, TERTIARY, and IDENTICAL. Although the interpretation of these strengths is locale-dependent, they generally have the following meanings:

PRIMARY

The comparison considers letter differences, but ignores case and diacriticals.

SECONDARY

The comparison considers letter differences and diacriticals, but ignores case.

TERTIARY

The comparison considers letter differences, case, and diacriticals.

IDENTICAL

The comparison considers all differences.

The default comparison strength is TERTIARY.

If you only need to compare two String objects once, the compare() method of the Collator class provides the best performance. However, if you need to compare the same String objects multiple times, such as when you are sorting, you should use CollationKey objects instead. A CollationKey object contains a String that has been converted into a series of bits that can be compared in a bitwise fashion against other CollationKey objects. You use a Collator object to create a CollationKey for a given String.

Class Summary

public abstract class java.text.Collator extends java.lang.Object
                      implements java.io.Serializable, 
                                 java.lang.Cloneable {
  // Constants
  public static final int CANONICAL_DECOMPOSITION;
  public static final int FULL_DECOMPOSITION;
  public static final int IDENTICAL;
  public static final int NO_DECOMPOSITION;
  public static final int PRIMARY;
  public static final int SECONDARY;
  public static final int TERTIARY;
  // Constructors
  protected Collator();
  // Class Methods
  public static synchronized Locale[] getAvailableLocales();
  public static synchronized Collator getInstance();
  public static synchronized Collator getInstance(Locale desiredLocale);
  // Instance Methods
  public Object clone();
  public abstract int compare(String source, String target);
  public boolean equals(Object that); 
  public boolean equals(String source, String target);
  public abstract CollationKey getCollationKey(String source);
  public synchronized int getDecomposition();
  public synchronized int getStrength();
  public abstract synchronized int hashCode();
  public synchronized void setDecomposition(int decompositionMode);
  public synchronized void setStrength(int newStrength);
}

Constants

CANONICAL_DECOMPOSITION

public final static int CANONICAL_DECOMPOSITION

Description: A decomposition constant that specifies that Unicode 2.0 characters which are canonical variants are decomposed for collation. This is the default decomposition setting.

FULL_DECOMPOSITION

public final static int FULL_DECOMPOSITION

Description: A decomposition constant that specifies that Unicode 2.0 canonical variants and compatibility variants are decomposed for collation. This is the most complete decomposition setting, and thus the slowest setting.

IDENTICAL

public final static int IDENTICAL

Description: A strength constant that specifies that all differences are considered significant for comparison purposes.

NO_DECOMPOSITION

public final static int NO_DECOMPOSITION

Description: A decomposition setting that specifies that no Unicode characters are decomposed for collation. This is the least complete decomposition setting, and thus the fastest setting. It only works correctly for languages that do not use diacriticals.

PRIMARY

public final static int PRIMARY

Description: A strength constant that specifies that only primary differences are considered significant for comparison purposes. Primary differences are typically letter differences.

SECONDARY

public final static int SECONDARY

Description: A strength constant that specifies that only secondary differences and above are considered significant for comparison purposes. Secondary differences are typically differences in diacriticals, or accents.

TERTIARY

public final static int TERTIARY

Description: A strength constant that specifies that only tertiary differences and above are considered significant for comparison purposes. Tertiary differences are typically differences in case. This is the default strength setting.

Constructors

Collator

protected Collator()

Description: This constructor creates a Collator with the default strength of TERTIARY and default decomposition mode of CANONICAL_DECOMPOSITION.

Class Methods

getAvailableLocales

public static synchronized Locale[] getAvailableLocales()

Returns

An array of Locale objects.

Description

This method returns an array of the Locale objects for which this class can create Collator objects.

getInstance

public static synchronized Collator getInstance()

Returns

A Collator appropriate for the default Locale.

Description

This method creates a Collator that compares strings in the default Locale.

 public static synchronized Collator getInstance( Locale desiredLocale)

Parameters

desiredLocale: The Locale to use.

Returns

A Collator appropriate for the given Locale.

Description

This method creates a Collator that compares strings in the given Locale.

Instance Methods

clone

public Object clone()

Returns

A copy of this Collator.

Overrides

Object.clone()

Description

This method creates a copy of this Collator and returns it.

compare

public abstract int compare(String source, String target)

Parameters

source

The source string.

target

The target string.

Returns

-1 if source is less than target, 0 if the strings are equal, or 1 if source is greater than target.

Description

This method compares the given strings according to the collation rules for this Collator and returns a value that indicates their relationship. If either of the strings are compared more than once, a CollationKey should be used instead.

equals

public boolean equals(Object that)

Parameters

that: The object to be compared with this object.

Returns

true if the objects are equal; false if they are not.

Overrides

Object.equals()

Description

This method returns true if obj is an instance of Collator and is equivalent to this Collator.

public boolean equals(String source, Source target)

Parameters

source

The source string.

target

The target string.

Returns

true if the given strings are equal; false otherwise.

Description

This method compares the given strings for equality using the collation rules for this Collator. Note that this method applies locale-specific rules and is thus not the same as String.equals().

getCollationKey

public abstract CollationKey getCollationKey(String source)

Parameters

source: The string to use when generating the CollationKey.

Returns

A CollationKey for the given string.

Description

This method generates a CollationKey for the given string. The returned object can be compared with other CollationKey objects using CollationKey.compareTo(). This comparison is faster than using Collator.compare(), so if the same string is used for many comparisons, you should use CollationKey objects.

getDecomposition

public synchronized int getDecomposition()

Returns

The decomposition mode for this Collator.

Description

This method returns the current decomposition mode for this Collator. The decomposition mode specifies how composed Unicode characters are handled during collation. You can adjust the decomposition mode to choose between faster and more complete collation. The returned value is one of the following values: NO_DECOMPOSITION, CANONICAL_DECOMPOSITION, or FULL_DECOMPOSITION.

getStrength

public synchronized int getStrength()

Returns

The strength setting for this Collator.

Description

This method returns the current strength setting for this Collator. The strength specifies the minimum level of difference that is considered significant during collation. The returned value is one of the following values: PRIMARY, SECONDARY, TERTIARY, or IDENTICAL.

hashCode

public abstract synchronized int hashCode()

Returns

A hashcode for this object.

Overrides

Object.hashCode()

Description

This method returns a hashcode for this Collator.

setDecomposition

public synchronized void setDecomposition(int decompositionMode)

Parameters

decompositionMode: The decomposition mode: NO_DECOMPOSITION, CANONICAL_DECOMPOSITION, or FULL_DECOMPOSITION.

Description

This method sets the decomposition mode for this Collator. The decomposition mode specifies how composed Unicode characters are handled during collation. You can adjust the decomposition mode to choose between faster and more complete collation.

setStrength

public synchronized void setStrength(int newStrength)

Parameters

newStrength: The new strength setting: PRIMARY, SECONDARY, TERTIARY, or IDENTICAL.

Description

This method sets the strength of this Collator. The strength specifies the minimum level of difference that is considered significant during collation.

Inherited Methods

Method	Inherited From	Method	Inherited From
`finalize()`	`Object`	`getClass()`	`Object`
`notify()`	`Object`	`notifyAll()`	`Object`
`toString()`	`Object`	`wait()`	`Object`
`wait(long)`	`Object`	`wait(long, int)`	`Object`