CollationKey

See also:

• Collator
• RuleBasedCollator

CollationKey

public CollationKey (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).

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.

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

equals

public boolean equals (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.

getBound

public CollationKey getBound (int boundType, 
                int noOfLevels)

Produces 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.

getSourceString

public String getSourceString ()

Return the source string that this CollationKey represents.

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.

merge

public CollationKey merge (CollationKey source)

Merges this CollationKey with another. The levels are merged with their corresponding counterparts (primaries with primaries, secondaries with secondaries etc.). Between the values from the same level a separator is inserted.

This is useful, for example, for combining sort keys from first and last names to sort such pairs. See http://www.unicode.org/reports/tr10/#Merging_Sort_Keys

The recommended way to achieve "merged" sorting is by concatenating strings with U+FFFE between them. The concatenation has the same sort order as the merged sort keys, but merge(getSortKey(str1), getSortKey(str2)) may differ from getSortKey(str1 + '\ufffe' + str2). Using strings with U+FFFE may yield shorter sort keys.

For details about Sort Key Features see https://unicode-org.github.io/icu/userguide/collation/api#sort-key-features

It is possible to merge multiple sort keys by consecutively merging another one with the intermediate result.

Only the sort key bytes of the CollationKeys are merged. This API does not attempt to merge the String representations of the CollationKeys, hence null will be returned as the result's String representation.

Example (uncompressed):

191B1D 01 050505 01 910505 00
 1F2123 01 050505 01 910505 00

191B1D 02 1F2123 01 050505 02 050505 01 910505 02 910505 00

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