Overview Package Class Use Source Tree Index Deprecated About
Prev Class | Next ClassFrames | No Frames
Summary: Nested | Field | Method | ConstrDetail: Nested | Field | Method | Constr

java.text

Class Collator

Implemented Interfaces:
Cloneable, Comparator<T>
Known Direct Subclasses:
RuleBasedCollator
public abstract class Collator
extends Object
implements Comparator<T>, 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.

Field Summary

static int
CANONICAL_DECOMPOSITION
This constant indicates that only characters which are canonical variants in Unicode 2.0 will be decomposed prior to performing comparisons.
static int
FULL_DECOMPOSITION
This constant indicates that both canonical variants and compatibility variants in Unicode 2.0 will be decomposed prior to performing comparisons.
static int
IDENTICAL
This constant is a strength value which indicates that any difference at all between character values are considered significant.
static int
NO_DECOMPOSITION
This constant indicates that accented characters won't be decomposed when performing comparisons.
static int
PRIMARY
This constant is a strength value which indicates that only primary differences between characters will be considered signficant.
static int
SECONDARY
This constant is a strength value which indicates that only secondary or primary differences between characters will be considered significant.
static int
TERTIARY
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

Object
clone()
This method returns a copy of this Collator object.
int
compare(Object o1, 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.
abstract int
compare(String source, 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.
boolean
equals(Object obj)
This method tests the specified object for equality against this object.
boolean
equals(String source, 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 Locale[]
getAvailableLocales()
This method returns an array of Locale objects which is the list of locales for which Collator objects exist.
abstract CollationKey
getCollationKey(String source)
This method transforms the specified String into a CollationKey for faster comparisons.
int
getDecomposition()
This method returns the current decomposition setting for this object.
static Collator
getInstance()
This method returns an instance of Collator for the default locale.
static Collator
getInstance(Locale loc)
This method returns an instance of Collator for the specified locale.
int
getStrength()
This method returns the current strength setting for this object.
abstract int
hashCode()
This method returns a hash code value for this object.
void
setDecomposition(int mode)
This method sets the decomposition setting for this object to the specified value.
void
setStrength(int strength)
This method sets the strength setting for this object to the specified value.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

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.
Field Value:
1

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.
Field Value:
2

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.
Field Value:
3

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.
Field Value:
0

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.
Field Value:
0

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.
Field Value:
1

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.
Field Value:
2

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.
Overrides:
clone in interface Object
Returns:
A duplicate of this object.

compare

public int compare(Object o1,
                   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:
o1 - The first object to compare
o2 - The second object to compare
Returns:
A negative integer if obj1 < obj2, 0 if obj1 == obj2, or a positive integer if obj1 > obj2.
Throws:
ClassCastException - If the arguments are not instances of String.

compare

public abstract int compare(String source,
                            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:
source - The first object to compare
target - The second object to compare
Returns:
A negative integer if str1 < str2, 0 if str1 == str2, or a positive integer if str1 > str2.

equals

public boolean equals(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.
Specified by:
equals in interface Comparator<T>
Overrides:
equals in interface Object
Parameters:
obj - The Object to test for equality against this object.
Returns:
true if the specified object is equal to this one, false otherwise.

equals

public boolean equals(String source,
                      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:
source - The first String to compare
target - The second String to compare
Returns:
true if the two strings are equal, false otherwise.

getAvailableLocales

public static 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 abstract CollationKey getCollationKey(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:
source - The String to convert.
Returns:
A CollationKey for the specified String.

getDecomposition

public 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(Locale loc)
This method returns an instance of Collator for the specified locale. If no Collator exists for the desired locale, the fallback procedure described in LocaleServiceProvider is invoked.
Parameters:
loc - The desired locale to load a Collator for.
Returns:
A Collator for the requested locale

getStrength

public 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 abstract int hashCode()
This method returns a hash code value for this object.
Overrides:
hashCode in interface Object
Returns:
A hash value for this object.

setDecomposition

public 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:
mode - The new decomposition setting.
Throws:
IllegalArgumentException - If the requested decomposition setting is not valid.

setStrength

public 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:
strength - The new strength setting.
Throws:
IllegalArgumentException - If the requested strength setting value is not valid.
Collator.java -- Perform locale dependent String comparisons. Copyright (C) 1998, 1999, 2000, 2001, 2004, 2005, 2007, 2008 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

Overview Package Class Use Source Tree Index Deprecated About