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

[Expand] Inherited Methods
From class java.lang.Object Object clone() Creates and returns a copy of this Object. boolean equals(Object o) Compares this instance with the specified object and indicates if they are equal. void finalize() Invoked when the garbage collector has detected that this instance is no longer reachable. final Class<?> getClass() Returns the unique instance of Class that represents this object's class. int hashCode() Returns an integer hash code for this object. final void notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. final void notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. String toString() Returns a string containing a concise, human-readable description of this object. final void wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object. final void wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires. final void wait(long millis) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
From interface java.lang.Comparable abstract int compareTo(T another) Compares this object to the specified object to determine their relative order.