public final class

CollationKey

extends Object
implements Comparable<T>
java.lang.Object
   ↳ java.text.CollationKey

Class Overview

Represents a string under the rules of a specific Collator object. Comparing two CollationKey instances returns the relative order of the strings they represent.

Since the rule set of collators can differ, the sort orders of the same string under two different Collator instances might differ. Hence comparing collation keys generated from different Collator instances can give incorrect results.

Both the method CollationKey.compareTo(CollationKey) and the method Collator.compare(String, String) compares two strings and returns their relative order. The performance characteristics of these two approaches can differ.

During the construction of a CollationKey, the entire source string is examined and processed into a series of bits terminated by a null, that are stored in the CollationKey. When CollationKey.compareTo(CollationKey) executes, it performs bitwise comparison on the bit sequences. This can incur startup cost when creating the CollationKey, but once the key is created, binary comparisons are fast. This approach is recommended when the same strings are to be compared over and over again.

On the other hand, implementations of Collator.compare(String, String) can examine and process the strings only until the first characters differ in order. This approach is recommended if the strings are to be compared only once.

The following example shows how collation keys can be used to sort a list of strings:

 // Create an array of CollationKeys for the Strings to be sorted.
 Collator myCollator = Collator.getInstance();
 CollationKey[] keys = new CollationKey[3];
 keys[0] = myCollator.getCollationKey("Tom");
 keys[1] = myCollator.getCollationKey("Dick");
 keys[2] = myCollator.getCollationKey("Harry");
 sort(keys);
 
//...
// Inside body of sort routine, compare keys this way if( keys[i].compareTo( keys[j] ) > 0 ) // swap keys[i] and keys[j]
//...
// Finally, when we've returned from sort. System.out.println(keys[0].getSourceString()); System.out.println(keys[1].getSourceString()); System.out.println(keys[2].getSourceString());

Summary

Public Methods
int compareTo(CollationKey value)
Compares this object to the specified collation key object to determine their relative order.
boolean equals(Object object)
Compares the specified object to this CollationKey and indicates if they are equal.
String getSourceString()
Returns the string from which this collation key was created.
int hashCode()
Returns an integer hash code for the receiver.
byte[] toByteArray()
Returns the collation key as a byte array.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.lang.Comparable

Public Methods

public int compareTo (CollationKey value)

Since: API Level 1

Compares this object to the specified collation key object to determine their relative order.

Parameters
value the collation key object to compare this object to.
Returns
  • a negative value if this CollationKey is less than the specified CollationKey, 0 if they are equal and a positive value if this CollationKey is greater.

public boolean equals (Object object)

Since: API Level 1

Compares the specified object to this CollationKey and indicates if they are equal. The object must be an instance of CollationKey and have the same source string and collation key. Both instances of CollationKey must have been created by the same Collator.

Parameters
object the object to compare to this object.
Returns
  • true if object is equal to this collation key; false otherwise.
See Also

public String getSourceString ()

Since: API Level 1

Returns the string from which this collation key was created.

Returns
  • the source string of this collation key.

public int hashCode ()

Since: API Level 1

Returns an integer hash code for the receiver. Objects which are equal return the same value for this method.

Returns
  • the receiver's hash.
See Also

public byte[] toByteArray ()

Since: API Level 1

Returns the collation key as a byte array.

Returns
  • an array of bytes.