Java Doc for CollationKey.java in  » Internationalization-Localization » icu4j » com » ibm » icu » text » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 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 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() );
 

This class is not subclassable

Compare this CollationKey to another CollationKey.

Compare this CollationKey with the specified Object.

Compare this CollationKey and the specified Object for equality.

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

Produce a bound for the sort order of a given collation key and a strength level.

Returns a hash code for this CollationKey.

Merges this CollationKey with another.

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.

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.

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.

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.

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

Produce a bound for the sort order of a given collation key and a strength level. This API does not attempt to find a bound for the CollationKey String representation, hence null will be returned in its place.

Resulting bounds can be used to produce a range of strings that are between upper and lower bounds. For example, if bounds are produced for a sortkey of string "smith", strings between upper and lower bounds with primary strength would include "Smith", "SMITH", "sMiTh".

There are two upper bounds that can be produced. If BoundMode.UPPER is produced, strings matched would be as above. However, if a bound is produced using BoundMode.UPPER_LONG is used, the above example will also match "Smithsonian" and similar.

For more on usage, see example in test procedure src/com/ibm/icu/dev/test/collator/CollationAPITest/TestBounds.

Collation keys produced may be compared using the compare API.

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.

Merges this CollationKey with another. Only the sorting order of the CollationKeys will be merged. This API does not attempt to merge the String representations of the CollationKeys, hence null will be returned as the String representation.

The strength levels are merged with their corresponding counterparts (PRIMARIES with PRIMARIES, SECONDARIES with SECONDARIES etc.).

The merged String representation of the result CollationKey will be a concatenation of the String representations of the 2 source CollationKeys.

Between the values from the same level a separator is inserted. example (uncompressed):

 
 191B1D 01 050505 01 910505 00 and 1F2123 01 050505 01 910505 00
 will be merged as 
 191B1D 02 1F212301 050505 02 050505 01 910505 02 910505 00
 

This allows for concatenating of first and last names for sorting, among other things.

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.");