|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.ibm.icu.text.Collator
public abstract class Collator
[icu enhancement] ICU's replacement for java.text.Collator
. Methods, fields, and other functionality specific to ICU are labeled '[icu]'.
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. |
static interface |
Collator.ReorderCodes
Reordering codes for non-script groups that can be reordered under collation. |
Field Summary | |
---|---|
static int |
CANONICAL_DECOMPOSITION
Decomposition mode value. |
static int |
FULL_DECOMPOSITION
[icu] Note: 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
[icu] 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()
Clones the collator. |
Collator |
cloneAsThawed()
Provides for the clone operation. |
int |
compare(Object source,
Object target)
Compares the source Object to the target Object. |
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)
Compares the equality of two text Strings using this Collator's rules, strength and decomposition mode. |
Collator |
freeze()
Freezes the collaotr. |
static Locale[] |
getAvailableLocales()
Returns the set of locales, as Locale objects, for which collators are installed. |
static ULocale[] |
getAvailableULocales()
[icu] Returns 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()
Returns the decomposition mode of this Collator. |
static String |
getDisplayName(Locale objectLocale)
[icu] Returns the name of the collator for the objectLocale, localized for the current locale. |
static String |
getDisplayName(Locale objectLocale,
Locale displayLocale)
[icu] Returns the name of the collator for the objectLocale, localized for the displayLocale. |
static String |
getDisplayName(ULocale objectLocale)
[icu] Returns the name of the collator for the objectLocale, localized for the current locale. |
static String |
getDisplayName(ULocale objectLocale,
ULocale displayLocale)
[icu] Returns the name of the collator for the objectLocale, localized for the displayLocale. |
static int[] |
getEquivalentReorderCodes(int reorderCode)
Retrieves all the reorder codes that are grouped with the given reorder code. |
static ULocale |
getFunctionalEquivalent(String keyword,
ULocale locID)
[icu] Returns 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)
[icu] Returns the functionally equivalent locale for the given requested locale, with respect to given keyword, for the collation service. |
static Collator |
getInstance()
Returns the Collator for the current default locale. |
static Collator |
getInstance(Locale locale)
Returns the Collator for the desired locale. |
static Collator |
getInstance(ULocale locale)
[icu] Returns the Collator for the desired locale. |
static String[] |
getKeywords()
[icu] Returns an array of all possible keywords that are relevant to collation. |
static String[] |
getKeywordValues(String keyword)
[icu] Given a keyword, returns an array of all values for that keyword that are currently in use. |
static String[] |
getKeywordValuesForLocale(String key,
ULocale locale,
boolean commonlyUsed)
[icu] Given a key and a locale, returns an array of string values in a preferred order that would make a difference. |
ULocale |
getLocale(ULocale.Type type)
[icu] Returns the locale that was used to create this object, or null. |
abstract RawCollationKey |
getRawCollationKey(String source,
RawCollationKey key)
[icu] Returns 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[] |
getReorderCodes()
Retrieves the reordering codes for this collator. |
int |
getStrength()
Returns this Collator's strength property. |
UnicodeSet |
getTailoredSet()
[icu] Returns a UnicodeSet that contains all the characters and sequences tailored in this collator. |
abstract VersionInfo |
getUCAVersion()
[icu] Returns the UCA version of this collator object. |
abstract int |
getVariableTop()
[icu] Returns the variable top value of a Collator. |
abstract VersionInfo |
getVersion()
[icu] Returns the version of this collator object. |
protected void |
internalSetDecomposition(int decomposition)
Internal set decompostion call to workaround frozen state because of self-modification in the RuleBasedCollator. |
boolean |
isFrozen()
Determines whether the object has been frozen or not. |
static Object |
registerFactory(Collator.CollatorFactory factory)
[icu] Registers a collator factory. |
static Object |
registerInstance(Collator collator,
ULocale locale)
[icu] Registers a collator as the default collator for the provided locale. |
void |
setDecomposition(int decomposition)
Sets the decomposition mode of this Collator. |
void |
setReorderCodes(int... order)
Sets the reordering codes for this collator. |
void |
setStrength(int newStrength)
Sets this Collator's strength property. |
Collator |
setStrength2(int newStrength)
Deprecated. This API is ICU internal only. |
abstract void |
setVariableTop(int varTop)
[icu] Sets the variable top to a collation element value supplied. |
abstract int |
setVariableTop(String varTop)
[icu] 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)
[icu] Unregisters 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
Note this value is different from JDK's
public static final int FULL_DECOMPOSITION
[icu] Note: This is for backwards compatibility with Java APIs only. It should not be used, IDENTICAL should be used instead. ICU's collation does not support Java's FULL_DECOMPOSITION mode.
public static final int NO_DECOMPOSITION
Note this value is different from the JDK's.
CANONICAL_DECOMPOSITION
,
getDecomposition()
,
setDecomposition(int)
,
Constant Field Valuespublic static final int CANONICAL_DECOMPOSITION
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)
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 Collator setStrength2(int newStrength)
public void setDecomposition(int decomposition)
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
protected void internalSetDecomposition(int decomposition)
decomposition
- public void setReorderCodes(int... order)
order
- the reordering codes to apply to this collator; if this is null or an empty array
then this clears any existing reorderinggetReorderCodes()
,
getEquivalentReorderCodes(int)
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 String[] getKeywordValuesForLocale(String key, ULocale locale, boolean commonlyUsed)
key
- one of the keys supported by this service. For now, only
"collation" is supported.locale
- the localecommonlyUsed
- if set to true it will return only commonly used values
with the given locale in preferred order. Otherwise,
it will return all the available values for the locale.
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()
[icu] Note: This can return QUATERNARY strength, which is not supported by the JDK version.
See the Collator class description for more details.
setStrength(int)
,
PRIMARY
,
SECONDARY
,
TERTIARY
,
QUATERNARY
,
IDENTICAL
public int getDecomposition()
See the Collator class description for more details.
setDecomposition(int)
,
NO_DECOMPOSITION
,
CANONICAL_DECOMPOSITION
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.String, java.lang.String)
public UnicodeSet getTailoredSet()
public abstract int compare(String source, String target)
source
- the source String.target
- the target String.
NullPointerException
- thrown if either argument is null.CollationKey
,
getCollationKey(java.lang.String)
public int compare(Object source, Object target)
compare
in interface Comparator<Object>
source
- the source Object.target
- the target Object.
ClassCastException
- thrown if either arguments cannot be cast to 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)
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 int[] getReorderCodes()
setReorderCodes(int...)
,
getEquivalentReorderCodes(int)
public static int[] getEquivalentReorderCodes(int reorderCode)
reorderCode
- code for which equivalents to be retrieved
setReorderCodes(int...)
,
getReorderCodes()
public boolean isFrozen()
isFrozen
in interface Freezable<Collator>
public Collator freeze()
freeze
in interface Freezable<Collator>
public Collator cloneAsThawed()
cloneAsThawed
in interface Freezable<Collator>
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 |