com.ibm.icu.text
Class CollationKey

java.lang.Object
  |
  +--com.ibm.icu.text.CollationKey
All Implemented Interfaces:
java.lang.Comparable

public final class CollationKey
extends java.lang.Object
implements java.lang.Comparable

A CollationKey represents a String under the rules of a specific Collator object. Comparing two CollationKeys 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 Collators might differ. Hence comparing CollationKeys generated from different Collators can give incorrect results.

Both the method CollationKey.compareTo(CollationKey) and the method Collator.compare(String, String) compare two strings and returns their relative order. The performance characterictics 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 that are stored in the CollationKey. When CollationKey.compareTo(CollationKey) executes, it performs bitwise comparison on the bit sequences. This can incurs 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 differing in order. This approach is recommended if the strings are to be compared only once.

More information about the composition of the bit sequence can be found in the user guide.

The following example shows how CollationKeys 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() );

Since:
release 2.2, April 18 2002
Author:
Syn Wee Quek
See Also:
Collator, RuleBasedCollator

Constructor Summary
CollationKey(java.lang.String source, byte[] key)
          CollationKey constructor.
 
Method Summary
 int compareTo(CollationKey target)
          Compare this CollationKey to another CollationKey.
 int compareTo(java.lang.Object obj)
          Compare this CollationKey with the specified Object.
 boolean equals(CollationKey target)
           Compare this CollationKey and the argument target CollationKey for equality.
 boolean equals(java.lang.Object target)
          Compare this CollationKey and the specified Object for equality.
 java.lang.String getSourceString()
          Return the source string that this CollationKey represents.
 int hashCode()
          Returns a hash code for this CollationKey.
 byte[] toByteArray()
          Duplicates and returns the value of this CollationKey as a sequence of big-endian bytes terminated by a null.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CollationKey

public CollationKey(java.lang.String source,
                    byte[] key)
CollationKey constructor. This constructor is given public access, unlike the JDK version, to allow access to users extending the Collator class. See Collator.getCollationKey(String).
Parameters:
source - string this CollationKey is to represent
key - array of bytes that represent the collation order of argument source
See Also:
Collator
Method Detail

getSourceString

public java.lang.String getSourceString()
Return the source string that this CollationKey represents.
Returns:
source string that this CollationKey represents

toByteArray

public byte[] toByteArray()

Duplicates and returns the value of this CollationKey as a sequence of big-endian bytes terminated by a null.

If two CollationKeys can be legitimately compared, then one can compare the byte arrays of each to obtain the same result, e.g.

 byte key1[] = collationkey1.toByteArray();
 byte key2[] = collationkey2.toByteArray();
 int key, targetkey;
 int i = 0;
 do {
	   key = key1[i] & 0xFF;
     targetkey = key2[i] & 0xFF;
     if (key < targetkey) {
         System.out.println("String 1 is less than string 2");
         return;
     }
     if (targetkey < key) {
         System.out.println("String 1 is more than string 2");
     }
     i ++;
 } while (key != 0 && targetKey != 0);

 System.out.println("Strings are equal.");
 

Returns:
CollationKey value in a sequence of big-endian byte bytes terminated by a null.

compareTo

public int compareTo(CollationKey target)

Compare this CollationKey to another CollationKey. The collation rules of the Collator that created this key are applied.

Note: Comparison between CollationKeys created by different Collators might return incorrect results. See class documentation.

Parameters:
target - target CollationKey
Returns:
an integer value. If the value is less than zero this CollationKey is less than than target, if the value is zero they are equal, and if the value is greater than zero this CollationKey is greater than target.
Throws:
NullPointerException - is thrown if argument is null.
See Also:
Collator.compare(String, String)

compareTo

public int compareTo(java.lang.Object obj)

Compare this CollationKey with the specified Object. The collation rules of the Collator that created this key are applied.

See note in compareTo(CollationKey) for warnings about possible incorrect results.

Specified by:
compareTo in interface java.lang.Comparable
Parameters:
obj - the Object to be compared to.
Returns:
Returns a negative integer, zero, or a positive integer respectively if this CollationKey is less than, equal to, or greater than the given Object.
Throws:
ClassCastException - is thrown when the argument is not a CollationKey. NullPointerException is thrown when the argument is null.
See Also:
compareTo(CollationKey)

equals

public boolean equals(java.lang.Object target)

Compare this CollationKey and the specified Object for equality. The collation rules of the Collator that created this key are applied.

See note in compareTo(CollationKey) for warnings about possible incorrect results.

Overrides:
equals in class java.lang.Object
Parameters:
target - the object to compare to.
Returns:
true if the two keys compare as equal, false otherwise.
Throws:
ClassCastException - is thrown when the argument is not a CollationKey. NullPointerException is thrown when the argument is null.
See Also:
compareTo(CollationKey)

equals

public boolean equals(CollationKey target)

Compare this CollationKey and the argument target CollationKey for equality. The collation rules of the Collator object which created these objects are applied.

See note in compareTo(CollationKey) for warnings of incorrect results

Parameters:
target - the CollationKey to compare to.
Returns:
true if two objects are equal, false otherwise.
Throws:
NullPointerException - is thrown when the argument is null.

hashCode

public int hashCode()

Returns a hash code for this CollationKey. The hash value is calculated on the key itself, not the String from which the key was created. Thus if x and y are CollationKeys, then x.hashCode(x) == y.hashCode() if x.equals(y) is true. This allows language-sensitive comparison in a hash table.

Overrides:
hashCode in class java.lang.Object
Returns:
the hash value.


Copyright (c) 2002 IBM Corporation and others.