Index (Frames) | Index (No Frames) | Package | Package Tree | Tree
java.text

Class Collator

java.lang.Object
|
+--java.text.Collator

All Implemented Interfaces:

Comparator, Cloneable


public abstract class Collator

extends Object

implements Comparator, Cloneable

This class is the abstract superclass of classes which perform locale dependent String comparisons. A caller requests an instance of Collator for a particular locale using the getInstance() static method in this class. That method will return a locale specific subclass of Collator which can be used to perform String comparisons for that locale. If a subclass of Collator cannot be located for a particular locale, a default instance for the current locale will be returned. In addition to setting the correct locale, there are two additional settings that can be adjusted to affect String comparisons: strength and decomposition. The strength value determines the level of signficance of character differences required for them to sort differently. (For example, whether or not capital letters are considered different from lower case letters). The decomposition value affects how variants of the same character are treated for sorting purposes. (For example, whether or not an accent is signficant or not). These settings are described in detail in the documentation for the methods and values that are related to them.

Authors:

Field Summary

static intCANONICAL_DECOMPOSITION

This constant indicates that only characters which are canonical variants in Unicode 2.0 will be decomposed prior to performing comparisons.
static intFULL_DECOMPOSITION

This constant indicates that both canonical variants and compatibility variants in Unicode 2.0 will be decomposed prior to performing comparisons.
static intIDENTICAL

This constant is a strength value which indicates that any difference at all between character values are considered significant.
static intNO_DECOMPOSITION

This constant indicates that accented characters won't be decomposed when performing comparisons.
static intPRIMARY

This constant is a strength value which indicates that only primary differences between characters will be considered signficant.
static intSECONDARY

This constant is a strength value which indicates that only secondary or primary differences between characters will be considered significant.
static intTERTIARY

This constant is a strength value which indicates that tertiary, secondary, and primary differences will be considered during sorting.

Constructor Summary

Collator()

This method initializes a new instance of Collator to have the default strength (TERTIARY) and decomposition (CANONICAL_DECOMPOSITION) settings.

Method Summary

java.lang.Objectclone()

This method returns a copy of this Collator object.
intcompare(java.lang.String source, java.lang.String target)

This method compares the two String's and returns an integer indicating whether or not the first argument is less than, equal to, or greater than the second argument.
intcompare(java.lang.Object o1, java.lang.Object o2)

This method compares the two Object's and returns an integer indicating whether or not the first argument is less than, equal to, or greater than the second argument.
booleanequals(java.lang.Object obj)

This method tests the specified object for equality against this object.
booleanequals(java.lang.String source, java.lang.String target)

This method tests whether the specified String's are equal according to the collation rules for the locale of this object and the current strength and decomposition settings.
static synchronized java.util.Locale[]getAvailableLocales()

This method returns an array of Locale objects which is the list of locales for which Collator objects exist.
java.text.CollationKeygetCollationKey(java.lang.String source)

This method transforms the specified String into a CollationKey for faster comparisons.
synchronized intgetDecomposition()

This method returns the current decomposition setting for this object.
static java.text.CollatorgetInstance()

This method returns an instance of Collator for the default locale.
static java.text.CollatorgetInstance(java.util.Locale loc)

This method returns an instance of Collator for the specified locale.
synchronized intgetStrength()

This method returns the current strength setting for this object.
inthashCode()

This method returns a hash code value for this object.
synchronized voidsetDecomposition(int mode)

This method sets the decomposition setting for this object to the specified value.
synchronized voidsetStrength(int strength)

This method sets the strength setting for this object to the specified value.

Field Details

CANONICAL_DECOMPOSITION

public static final int CANONICAL_DECOMPOSITION

This constant indicates that only characters which are canonical variants in Unicode 2.0 will be decomposed prior to performing comparisons. This will cause accented languages to be sorted correctly. This is the default decomposition value.


FULL_DECOMPOSITION

public static final int FULL_DECOMPOSITION

This constant indicates that both canonical variants and compatibility variants in Unicode 2.0 will be decomposed prior to performing comparisons. This is the slowest mode, but is required to get the correct sorting for certain languages with certain special formats.


IDENTICAL

public static final int IDENTICAL

This constant is a strength value which indicates that any difference at all between character values are considered significant.


NO_DECOMPOSITION

public static final int NO_DECOMPOSITION

This constant indicates that accented characters won't be decomposed when performing comparisons. This will yield the fastest results, but will only work correctly in call cases for languages which do not use accents such as English.


PRIMARY

public static final int PRIMARY

This constant is a strength value which indicates that only primary differences between characters will be considered signficant. As an example, two completely different English letters such as 'a' and 'b' are considered to have a primary difference.


SECONDARY

public static final int SECONDARY

This constant is a strength value which indicates that only secondary or primary differences between characters will be considered significant. An example of a secondary difference between characters are instances of the same letter with different accented forms.


TERTIARY

public static final int TERTIARY

This constant is a strength value which indicates that tertiary, secondary, and primary differences will be considered during sorting. An example of a tertiary difference is capitalization of a given letter. This is the default value for the strength setting.


Constructor Details

Collator

protected Collator()

This method initializes a new instance of Collator to have the default strength (TERTIARY) and decomposition (CANONICAL_DECOMPOSITION) settings. This constructor is protected and is for use by subclasses only. Non-subclass callers should use the static getInstance() methods of this class to instantiate Collation objects for the desired locale.


Method Details

clone

public Object clone()

This method returns a copy of this Collator object.

Returns:


compare

public int compare(java.lang.Object o1, java.lang.Object o2)

This method compares the two Object's and returns an integer indicating whether or not the first argument is less than, equal to, or greater than the second argument. These two objects must be String's or an exception will be thrown.

Parameters:

Returns:

Throws:


compare

public int compare(java.lang.String source, java.lang.String target)

This method compares the two String's and returns an integer indicating whether or not the first argument is less than, equal to, or greater than the second argument. The comparison is performed according to the rules of the locale for this Collator and the strength and decomposition rules in effect.

Parameters:

Returns:


equals

public boolean equals(java.lang.Object obj)

This method tests the specified object for equality against this object. This will be true if and only if the following conditions are met:

Parameters:

Returns:


equals

public boolean equals(java.lang.String source, java.lang.String target)

This method tests whether the specified String's are equal according to the collation rules for the locale of this object and the current strength and decomposition settings.

Parameters:

Returns:


getAvailableLocales

public static synchronized Locale[] getAvailableLocales()

This method returns an array of Locale objects which is the list of locales for which Collator objects exist.

Returns:


getCollationKey

public CollationKey getCollationKey(java.lang.String source)

This method transforms the specified String into a CollationKey for faster comparisons. This is useful when comparisons against a string might be performed multiple times, such as during a sort operation.

Parameters:

Returns:


getDecomposition

public synchronized int getDecomposition()

This method returns the current decomposition setting for this object. This * will be one of NO_DECOMPOSITION, CANONICAL_DECOMPOSITION, or * FULL_DECOMPOSITION. See the documentation for those constants for an * explanation of this setting.

Returns:


getInstance

public static Collator getInstance()

This method returns an instance of Collator for the default locale.

Returns:


getInstance

public static Collator getInstance(java.util.Locale loc)

This method returns an instance of Collator for the specified locale. If no Collator exists for the desired locale, a Collator for the default locale will be returned.

Parameters:

Returns:


getStrength

public synchronized int getStrength()

This method returns the current strength setting for this object. This will be one of PRIMARY, SECONDARY, TERTIARY, or IDENTICAL. See the documentation for those constants for an explanation of this setting.

Returns:


hashCode

public int hashCode()

This method returns a hash code value for this object.

Returns:


setDecomposition

public synchronized void setDecomposition(int mode)

This method sets the decomposition setting for this object to the specified value. This must be one of NO_DECOMPOSITION, CANONICAL_DECOMPOSITION, or FULL_DECOMPOSITION. Otherwise an exception will be thrown. See the documentation for those contants for an explanation of this setting.

Parameters:

Throws:


setStrength

public synchronized void setStrength(int strength)

This method sets the strength setting for this object to the specified value. This must be one of PRIMARY, SECONDARY, TERTIARY, or IDENTICAL. Otherwise an exception is thrown. See the documentation for these constants for an explanation of this setting.

Parameters:

Throws: