File Doc Category Size Date Package
Collator.java API Doc Android 1.5 API 17461 Wed May 06 22:41:06 BST 2009 java.text

Collator

java.lang.Object

public abstract class Collator extends Object implements Cloneable, Comparator

Performs locale-sensitive string comparison. A concrete subclass, {@link 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 4 different levels of strength used in comparisons:

PRIMARY strength: Typically, this is used to denote differences between base characters (for example, "a" < "b"). It is the strongest difference. For example, dictionaries are divided into different sections by base character.
SECONDARY strength: Accents in the characters are considered secondary differences (for example, "as" < "às" < "at"). Other differences between letters can also be considered secondary differences, depending on the language. A secondary difference is ignored when there is a primary difference anywhere in the strings.
TERTIARY strength: Upper and lower case differences in characters are distinguished at tertiary strength (for example, "ao" < "Ao" < "aò"). In addition, a variant of a letter differs from the base form on the tertiary strength (such as "A" and "Ⓐ"). Another example is the difference between large and small Kana. A tertiary difference is ignored when there is a primary or secondary difference anywhere in the strings.
IDENTICAL strength: 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. For example, Hebrew cantellation marks are only distinguished at this strength. This strength should be used sparingly, as only code point value differences between two strings are an extremely rare occurrence. Using this strength substantially decreases the performance for both comparison and collation key generation APIs. This strength also increases the size of the collation key.

This {@code Collator} deals only with two decomposition modes, the canonical decomposition mode and one that does not use any decomposition. The compatibility decomposition mode {@code java.text.Collator.FULL_DECOMPOSITION} is not supported here. If the canonical decomposition mode is set, {@code Collator} handles un-normalized text properly, producing the same results as if the text were normalized in NFD. If canonical decomposition is turned off, it is the user's responsibility to ensure that all text is already in the appropriate form before performing a comparison or before getting a {@link CollationKey}.

Examples:

// 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(Collator.NO_DECOMPOSITION);
if (myCollator.compare("\u00e0\u0325", "a\u0325\u0300") != 0) {
System.out.println("\u00e0\u0325 is not equal to a\u0325\u0300 without decomposition");
myCollator.setDecomposition(Collator.CANONICAL_DECOMPOSITION);
if (myCollator.compare("\u00e0\u0325", "a\u0325\u0300") != 0) {
System.out.println("Error: \u00e0\u0325 should be equal to a\u0325\u0300 with decomposition");
} else {
System.out.println("\u00e0\u0325 is equal to a\u0325\u0300 with decomposition");
}
} else {
System.out.println("Error: \u00e0\u0325 should be not equal to a\u0325\u0300 without decomposition");
}

see: RuleBasedCollator
see: CollationKey
since: Android 1.0

Fields Summary
static final int
EQUAL
static final int
GREATER
static final int
LESS
public static final int
NO_DECOMPOSITION
Constant used to specify the decomposition rule.
public static final int
CANONICAL_DECOMPOSITION
Constant used to specify the decomposition rule.
public static final int
FULL_DECOMPOSITION
Constant used to specify the decomposition rule. This value for decomposition is not supported.
public static final int
PRIMARY
Constant used to specify the collation strength.
public static final int
SECONDARY
Constant used to specify the collation strength.
public static final int
TERTIARY
Constant used to specify the collation strength.
public static final int
IDENTICAL
Constant used to specify the collation strength.
private static int
CACHE_SIZE
private static Vector
cache
com.ibm.icu4jni.text.Collator
icuColl
Constructors Summary
Collator(com.ibm.icu4jni.text.Collator wrapper)
this.icuColl = wrapper;
protected Collator()
Constructs a new {@code Collator} instance.
since
Android 1.0
super(); // BEGIN android-added icuColl = com.ibm.icu4jni.text.Collator.getInstance(Locale.getDefault()); // END android-added
Methods Summary
public java.lang.Object clone()
Returns a new collator with the same decomposition mode and strength value as this collator.
return
a shallow copy of this collator.
see
java.lang.Cloneable
since
Android 1.0
try { Collator clone = (Collator) super.clone(); clone.icuColl = (com.ibm.icu4jni.text.Collator) this.icuColl.clone(); return clone; } catch (CloneNotSupportedException e) { return null; }
public int compare(java.lang.Object object1, java.lang.Object object2)
Compares two objects to determine their relative order. The objects must be strings.
param
object1 the first string to compare.
param
object2 the second string to compare.
return
a negative value if {@code object1} is less than {@code object2}, 0 if they are equal, and a positive value if {@code object1} is greater than {@code object2}.
exception
ClassCastException if {@code object1} or {@code object2} is not a {@code String}.
since
Android 1.0
return compare((String) object1, (String) object2);
public abstract int compare(java.lang.String string1, java.lang.String string2)
Compares two strings to determine their relative order.
param
string1 the first string to compare.
param
string2 the second string to compare.
return
a negative value if {@code string1} is less than {@code string2}, 0 if they are equal and a positive value if {@code string1} is greater than {@code string2}.
since
Android 1.0
private int decompositionMode_ICU_Java(int mode)
int javaMode = mode; switch (mode) { case com.ibm.icu4jni.text.Collator.NO_DECOMPOSITION: javaMode = Collator.NO_DECOMPOSITION; break; case com.ibm.icu4jni.text.Collator.CANONICAL_DECOMPOSITION: javaMode = Collator.CANONICAL_DECOMPOSITION; break; } return javaMode;
private int decompositionMode_Java_ICU(int mode)
int icuDecomp = mode; switch (mode) { case Collator.CANONICAL_DECOMPOSITION: icuDecomp = com.ibm.icu4jni.text.Collator.CANONICAL_DECOMPOSITION; break; case Collator.NO_DECOMPOSITION: icuDecomp = com.ibm.icu4jni.text.Collator.NO_DECOMPOSITION; break; } return icuDecomp;
public boolean equals(java.lang.Object object)
Compares this collator with the specified object and indicates if they are equal.
param
object the object to compare with this object.
return
{@code true} if {@code object} is a {@code Collator} object and it has the same strength and decomposition values as this collator; {@code false} otherwise.
see
#hashCode
since
Android 1.0
if (!(object instanceof Collator)) { return false; } Collator collator = (Collator) object; return this.icuColl == null ? collator.icuColl == null : this.icuColl .equals(collator.icuColl);
public boolean equals(java.lang.String string1, java.lang.String string2)
Compares two strings using the collation rules to determine if they are equal.
param
string1 the first string to compare.
param
string2 the second string to compare.
return
{@code true} if {@code string1} and {@code string2} are equal using the collation rules, false otherwise.
since
Android 1.0
return compare(string1, string2) == 0;
public static java.util.Locale[] getAvailableLocales()
Gets the list of installed {@link java.util.Locale} objects which support {@code Collator}.
return
an array of {@code Locale}.
since
Android 1.0
return com.ibm.icu4jni.text.Collator.getAvailableLocales();
public abstract java.text.CollationKey getCollationKey(java.lang.String string)
Returns a {@link CollationKey} for the specified string for this collator with the current decomposition rule and strength value.
param
string the source string that is converted into a collation key.
return
the collation key for {@code string}.
since
Android 1.0
public int getDecomposition()
Returns the decomposition rule for this collator.
return
the decomposition rule, either {@code NO_DECOMPOSITION} or {@code CANONICAL_DECOMPOSITION}. {@code FULL_DECOMPOSITION} is not supported.
since
Android 1.0
return decompositionMode_ICU_Java(this.icuColl.getDecomposition());
public static java.text.Collator getInstance()
Returns a {@code Collator} instance which is appropriate for the default {@code Locale}.
return
the collator for the default locale.
since
Android 1.0
return getInstance(Locale.getDefault());
public static java.text.Collator getInstance(java.util.Locale locale)
Returns a {@code Collator} instance which is appropriate for the specified {@code Locale}.
param
locale the locale.
return
the collator for {@code locale}.
since
Android 1.0
String key = locale.toString(); for (int i = cache.size() - 1; i >= 0; i -= 2) { if (cache.elementAt(i).equals(key)) { return (Collator) (cache.elementAt(i - 1)).clone(); } } return new RuleBasedCollator(com.ibm.icu4jni.text.Collator .getInstance(locale));
public int getStrength()
Returns the strength value for this collator.
return
the strength value, either PRIMARY, SECONDARY, TERTIARY or IDENTICAL.
since
Android 1.0
return strength_ICU_Java(this.icuColl.getStrength());
public abstract int hashCode()
Returns an integer hash code for this collator.
return
this collator's hash code.
see
#equals(Object)
see
#equals(String, String)
since
Android 1.0
public void setDecomposition(int value)
Sets the decomposition rule for this collator.
param
value the decomposition rule, either {@code NO_DECOMPOSITION} or {@code CANONICAL_DECOMPOSITION}. {@code FULL_DECOMPOSITION} is not supported.
exception
IllegalArgumentException if the provided decomposition rule is not valid. This includes {@code FULL_DECOMPOSITION}.
since
Android 1.0
this.icuColl.setDecomposition(decompositionMode_Java_ICU(value));
public void setStrength(int value)
Sets the strength value for this collator.
param
value the strength value, either PRIMARY, SECONDARY, TERTIARY, or IDENTICAL.
exception
IllegalArgumentException if the provided strength value is not valid.
since
Android 1.0
this.icuColl.setStrength(strength_Java_ICU(value));
private int strength_ICU_Java(int value)
int javaValue = value; switch (value) { case com.ibm.icu4jni.text.Collator.PRIMARY: javaValue = Collator.PRIMARY; break; case com.ibm.icu4jni.text.Collator.SECONDARY: javaValue = Collator.SECONDARY; break; case com.ibm.icu4jni.text.Collator.TERTIARY: javaValue = Collator.TERTIARY; break; case com.ibm.icu4jni.text.Collator.IDENTICAL: javaValue = Collator.IDENTICAL; break; } return javaValue;
private int strength_Java_ICU(int value)
int icuValue = value; switch (value) { case Collator.PRIMARY: icuValue = com.ibm.icu4jni.text.Collator.PRIMARY; break; case Collator.SECONDARY: icuValue = com.ibm.icu4jni.text.Collator.SECONDARY; break; case Collator.TERTIARY: icuValue = com.ibm.icu4jni.text.Collator.TERTIARY; break; case Collator.IDENTICAL: icuValue = com.ibm.icu4jni.text.Collator.IDENTICAL; break; } return icuValue;