|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.ibm.icu.text.Collator
public abstract class Collator
Collator performs locale-sensitive string comparison. A concrete subclass, RuleBasedCollator, allows customization of the collation ordering by the use of rule sets.
Following the Unicode Consortium's specifications for the Unicode Collation Algorithm (UCA), there are 5 different levels of strength used in comparisons:
For more information about the collation service see the users guide.
Examples of use
// Get the Collator for US English and set its strength to PRIMARY Collator usCollator = Collator.getInstance(Locale.US); usCollator.setStrength(Collator.PRIMARY); if (usCollator.compare("abc", "ABC") == 0) { System.out.println("Strings are equivalent"); } The following example shows how to compare two strings using the Collator for the default locale. // Compare two strings in the default locale Collator myCollator = Collator.getInstance(); myCollator.setDecomposition(NO_DECOMPOSITION); if (myCollator.compare("à\u0325", "a\u0325̀") != 0) { System.out.println("à\u0325 is not equals to a\u0325̀ without decomposition"); myCollator.setDecomposition(CANONICAL_DECOMPOSITION); if (myCollator.compare("à\u0325", "a\u0325̀") != 0) { System.out.println("Error: à\u0325 should be equals to a\u0325̀ with decomposition"); } else { System.out.println("à\u0325 is equals to a\u0325̀ with decomposition"); } } else { System.out.println("Error: à\u0325 should be not equals to a\u0325̀ without decomposition"); }
RuleBasedCollator
,
CollationKey
Nested Class Summary | |
---|---|
static class |
Collator.CollatorFactory
A factory used with registerFactory to register multiple collators and provide display names for them. |
Field Summary | |
---|---|
static int |
CANONICAL_DECOMPOSITION
Decomposition mode value. |
static int |
FULL_DECOMPOSITION
This is for backwards compatibility with Java APIs only. |
static int |
IDENTICAL
Smallest Collator strength value. |
static int |
NO_DECOMPOSITION
Decomposition mode value. |
static int |
PRIMARY
Strongest collator strength value. |
static int |
QUATERNARY
Fourth level collator strength value. |
static int |
SECONDARY
Second level collator strength value. |
static int |
TERTIARY
Third level collator strength value. |
Constructor Summary | |
---|---|
protected |
Collator()
Empty default constructor to make javadocs happy |
Method Summary | |
---|---|
Object |
clone()
Clone the collator. |
int |
compare(Object source,
Object target)
Compares the source text String to the target text String according to this Collator's rules, strength and decomposition mode. |
abstract int |
compare(String source,
String target)
Compares the source text String to the target text String according to this Collator's rules, strength and decomposition mode. |
boolean |
equals(String source,
String target)
Convenience method for comparing the equality of two text Strings using this Collator's rules, strength and decomposition mode. |
static Locale[] |
getAvailableLocales()
Get the set of locales, as Locale objects, for which collators are installed. |
static ULocale[] |
getAvailableULocales()
Get the set of locales, as ULocale objects, for which collators are installed. |
abstract CollationKey |
getCollationKey(String source)
Transforms the String into a CollationKey suitable for efficient repeated comparison. |
int |
getDecomposition()
Get the decomposition mode of this Collator. |
static String |
getDisplayName(Locale objectLocale)
Get the name of the collator for the objectLocale, localized for the current locale. |
static String |
getDisplayName(Locale objectLocale,
Locale displayLocale)
Get the name of the collator for the objectLocale, localized for the displayLocale. |
static String |
getDisplayName(ULocale objectLocale)
Get the name of the collator for the objectLocale, localized for the current locale. |
static String |
getDisplayName(ULocale objectLocale,
ULocale displayLocale)
Get the name of the collator for the objectLocale, localized for the displayLocale. |
static ULocale |
getFunctionalEquivalent(String keyword,
ULocale locID)
Return the functionally equivalent locale for the given requested locale, with respect to given keyword, for the collation service. |
static ULocale |
getFunctionalEquivalent(String keyword,
ULocale locID,
boolean[] isAvailable)
Return the functionally equivalent locale for the given requested locale, with respect to given keyword, for the collation service. |
static Collator |
getInstance()
Gets the Collator for the current default locale. |
static Collator |
getInstance(Locale locale)
Gets the Collator for the desired locale. |
static Collator |
getInstance(ULocale locale)
Gets the Collator for the desired locale. |
static String[] |
getKeywords()
Return an array of all possible keywords that are relevant to collation. |
static String[] |
getKeywordValues(String keyword)
Given a keyword, return an array of all values for that keyword that are currently in use. |
ULocale |
getLocale(ULocale.Type type)
Return the locale that was used to create this object, or null. |
abstract RawCollationKey |
getRawCollationKey(String source,
RawCollationKey key)
Gets the simpler form of a CollationKey for the String source following the rules of this Collator and stores the result into the user provided argument key. |
int |
getStrength()
Returns this Collator's strength property. |
UnicodeSet |
getTailoredSet()
Get an UnicodeSet that contains all the characters and sequences tailored in this collator. |
abstract VersionInfo |
getUCAVersion()
Get the UCA version of this collator object. |
abstract int |
getVariableTop()
Gets the variable top value of a Collator. |
abstract VersionInfo |
getVersion()
Get the version of this collator object. |
static Object |
registerFactory(Collator.CollatorFactory factory)
Register a collator factory. |
static Object |
registerInstance(Collator collator,
ULocale locale)
Register a collator as the default collator for the provided locale. |
void |
setDecomposition(int decomposition)
Set the decomposition mode of this Collator. |
void |
setStrength(int newStrength)
Sets this Collator's strength property. |
abstract void |
setVariableTop(int varTop)
Sets the variable top to a collation element value supplied. |
abstract int |
setVariableTop(String varTop)
Variable top is a two byte primary value which causes all the codepoints with primary values that are less or equal than the variable top to be shifted when alternate handling is set to SHIFTED. |
static boolean |
unregister(Object registryKey)
Unregister a collator previously registered using registerInstance. |
Methods inherited from class java.lang.Object |
---|
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Methods inherited from interface java.util.Comparator |
---|
equals |
Field Detail |
---|
public static final int PRIMARY
setStrength(int)
,
getStrength()
,
Constant Field Valuespublic static final int SECONDARY
setStrength(int)
,
getStrength()
,
Constant Field Valuespublic static final int TERTIARY
setStrength(int)
,
getStrength()
,
Constant Field Valuespublic static final int QUATERNARY
setStrength(int)
,
getStrength()
,
Constant Field Valuespublic static final int IDENTICAL
Smallest Collator strength value. When all other strengths are equal, the IDENTICAL strength is used as a tiebreaker. The Unicode code point values of the NFD form of each string are compared, just in case there is no difference. See class documentation for more explanation.
Note this value is different from JDK's
public static final int FULL_DECOMPOSITION
public static final int NO_DECOMPOSITION
Decomposition mode value. With NO_DECOMPOSITION set, Strings will not be decomposed for collation. This is the default decomposition setting unless otherwise specified by the locale used to create the Collator.
Note this value is different from the JDK's.
CANONICAL_DECOMPOSITION
,
getDecomposition()
,
setDecomposition(int)
,
Constant Field Valuespublic static final int CANONICAL_DECOMPOSITION
Decomposition mode value. With CANONICAL_DECOMPOSITION set, characters that are canonical variants according to the Unicode standard will be decomposed for collation.
CANONICAL_DECOMPOSITION corresponds to Normalization Form D as described in Unicode Technical Report #15.
NO_DECOMPOSITION
,
getDecomposition()
,
setDecomposition(int)
,
Constant Field ValuesConstructor Detail |
---|
protected Collator()
Method Detail |
---|
public void setStrength(int newStrength)
Sets this Collator's strength property. The strength property determines the minimum level of difference considered significant during comparison.
The default strength for the Collator is TERTIARY, unless specified otherwise by the locale used to create the Collator.
See the Collator class description for an example of use.
newStrength
- the new strength value.
IllegalArgumentException
- if the new strength value is not one
of PRIMARY, SECONDARY, TERTIARY, QUATERNARY or IDENTICAL.getStrength()
,
PRIMARY
,
SECONDARY
,
TERTIARY
,
QUATERNARY
,
IDENTICAL
public void setDecomposition(int decomposition)
Set the decomposition mode of this Collator. Setting this decomposition property with CANONICAL_DECOMPOSITION allows the Collator to handle un-normalized text properly, producing the same results as if the text were normalized. If NO_DECOMPOSITION is set, it is the user's responsibility to insure that all text is already in the appropriate form before a comparison or before getting a CollationKey. Adjusting decomposition mode allows the user to select between faster and more complete collation behavior.
Since a great many of the world's languages do not require text normalization, most locales set NO_DECOMPOSITION as the default decomposition mode.
The default decompositon mode for the Collator is NO_DECOMPOSITON, unless specified otherwise by the locale used to create the Collator.See getDecomposition for a description of decomposition mode.
decomposition
- the new decomposition mode
IllegalArgumentException
- If the given value is not a valid
decomposition mode.getDecomposition()
,
NO_DECOMPOSITION
,
CANONICAL_DECOMPOSITION
public static final Collator getInstance()
Locale.getDefault()
,
getInstance(Locale)
public Object clone() throws CloneNotSupportedException
clone
in class Object
CloneNotSupportedException
public static final Collator getInstance(ULocale locale)
locale
- the desired locale.
Locale
,
ResourceBundle
,
getInstance(Locale)
,
getInstance()
public static final Collator getInstance(Locale locale)
locale
- the desired locale.
Locale
,
ResourceBundle
,
getInstance(ULocale)
,
getInstance()
public static final Object registerInstance(Collator collator, ULocale locale)
collator
- the collator to registerlocale
- the locale for which this is the default collator
public static final Object registerFactory(Collator.CollatorFactory factory)
factory
- the factory to register
public static final boolean unregister(Object registryKey)
registryKey
- the object previously returned by registerInstance.
public static Locale[] getAvailableLocales()
public static final ULocale[] getAvailableULocales()
public static final String[] getKeywords()
getKeywordValues(java.lang.String)
public static final String[] getKeywordValues(String keyword)
keyword
- one of the keywords returned by getKeywords.getKeywords()
public static final ULocale getFunctionalEquivalent(String keyword, ULocale locID, boolean[] isAvailable)
keyword
- a particular keyword as enumerated by
getKeywords.locID
- The requested localeisAvailable
- If non-null, isAvailable[0] will receive and
output boolean that indicates whether the requested locale was
'available' to the collation service. If non-null, isAvailable
must have length >= 1.
public static final ULocale getFunctionalEquivalent(String keyword, ULocale locID)
keyword
- a particular keyword as enumerated by
getKeywords.locID
- The requested locale
getFunctionalEquivalent(String,ULocale,boolean[])
public static String getDisplayName(Locale objectLocale, Locale displayLocale)
objectLocale
- the locale of the collatordisplayLocale
- the locale for the collator's display name
public static String getDisplayName(ULocale objectLocale, ULocale displayLocale)
objectLocale
- the locale of the collatordisplayLocale
- the locale for the collator's display name
public static String getDisplayName(Locale objectLocale)
objectLocale
- the locale of the collator
public static String getDisplayName(ULocale objectLocale)
objectLocale
- the locale of the collator
public int getStrength()
Returns this Collator's strength property. The strength property determines the minimum level of difference considered significant.
See the Collator class description for more details.
setStrength(int)
,
PRIMARY
,
SECONDARY
,
TERTIARY
,
QUATERNARY
,
IDENTICAL
public int getDecomposition()
Get the decomposition mode of this Collator. Decomposition mode determines how Unicode composed characters are handled.
See the Collator class description for more details.
setDecomposition(int)
,
NO_DECOMPOSITION
,
CANONICAL_DECOMPOSITION
public int compare(Object source, Object target)
Compares the source text String to the target text String according to this Collator's rules, strength and decomposition mode. Returns an integer less than, equal to or greater than zero depending on whether the source String is less than, equal to or greater than the target String. See the Collator class description for an example of use.
compare
in interface Comparator
source
- the source String.target
- the target String.
NullPointerException
- thrown if either arguments is null.
IllegalArgumentException thrown if either source or target is
not of the class String.CollationKey
,
getCollationKey(java.lang.String)
public boolean equals(String source, String target)
source
- the source string to be compared.target
- the target string to be compared.
NullPointerException
- thrown if either arguments is null.compare(java.lang.Object, java.lang.Object)
public UnicodeSet getTailoredSet()
public abstract int compare(String source, String target)
Compares the source text String to the target text String according to this Collator's rules, strength and decomposition mode. Returns an integer less than, equal to or greater than zero depending on whether the source String is less than, equal to or greater than the target String. See the Collator class description for an example of use.
source
- the source String.target
- the target String.
NullPointerException
- thrown if either arguments is null.CollationKey
,
getCollationKey(java.lang.String)
public abstract CollationKey getCollationKey(String source)
Transforms the String into a CollationKey suitable for efficient repeated comparison. The resulting key depends on the collator's rules, strength and decomposition mode.
See the CollationKey class documentation for more information.
source
- the string to be transformed into a CollationKey.
CollationKey
,
compare(String, String)
,
getRawCollationKey(java.lang.String, com.ibm.icu.text.RawCollationKey)
public abstract RawCollationKey getRawCollationKey(String source, RawCollationKey key)
source
- the text String to be transformed into a RawCollationKey
compare(String, String)
,
getCollationKey(java.lang.String)
,
RawCollationKey
public abstract int setVariableTop(String varTop)
Variable top is a two byte primary value which causes all the codepoints with primary values that are less or equal than the variable top to be shifted when alternate handling is set to SHIFTED.
Sets the variable top to a collation element value of a string supplied.
varTop
- one or more (if contraction) characters to which the
variable top should be set
IllegalArgumentException
- is thrown if varTop argument is not
a valid variable top element. A variable top element is
invalid when it is a contraction that does not exist in the
Collation order or when the PRIMARY strength collation
element for the variable top has more than two bytesgetVariableTop()
,
RuleBasedCollator.setAlternateHandlingShifted(boolean)
public abstract int getVariableTop()
setVariableTop(java.lang.String)
public abstract void setVariableTop(int varTop)
varTop
- Collation element value, as returned by setVariableTop or
getVariableTopgetVariableTop()
,
setVariableTop(java.lang.String)
public abstract VersionInfo getVersion()
public abstract VersionInfo getUCAVersion()
public final ULocale getLocale(ULocale.Type type)
Note: This method will be implemented in ICU 3.0; ICU 2.8 contains a partial preview implementation. The * actual locale is returned correctly, but the valid locale is not, in most cases.
type
- type of information requested, either ULocale.VALID_LOCALE
or ULocale.ACTUAL_LOCALE
.
ULocale
,
ULocale.VALID_LOCALE
,
ULocale.ACTUAL_LOCALE
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |