java.text
Class Collator
java.lang.Object
|
+--java.text.Collator
All Implemented Interfaces:
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:- Tom Tromey <tromey@cygnus.com>
- Aaron M. Renn (arenn@urbanophile.com)
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.
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.
clone
public Object clone()
This method returns a copy of this Collator
object.
Returns:
- A duplicate of this object.
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:
- A negative integer if obj1 < obj2, 0 if obj1 == obj2, or
a positive integer if obj1 > obj2.
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:
- A negative integer if str1 < str2, 0 if str1 == str2, or
a positive integer if str1 > str2.
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:
- The specified object is not
null
.
- The specified object is an instance of
Collator
.
- The specified object has the same strength and decomposition
settings as this object.
Parameters:
Returns:
true
if the specified object is equal to
this one, false
otherwise.
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:
true
if the two strings are equal,
false
otherwise.
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:
- The list of locales for which
Collator
's exist.
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:
- A
CollationKey
for the specified String
.
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:
- The current decomposition setting.
getInstance
public static Collator getInstance()
This method returns an instance of Collator
for the
default locale.
Returns:
- A
Collator
for the default locale.
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:
- A
Collator
for the requested locale
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:
- The current strength setting.
hashCode
public int hashCode()
This method returns a hash code value for this object.
Returns:
- A hash value for this object.
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:
String
comparisons. A caller requests an instance ofCollator
for a particular locale using thegetInstance()
static method in this class. That method will return a locale specific subclass ofCollator
which can be used to performString
comparisons for that locale. If a subclass ofCollator
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 affectString
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.