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

string this CollationKey is to represent

key:byte[]

array of bytes that represent the collation order of argument source terminated by a null

ICU Status

Stable since ICU 2.8.

See Also

Collator

CollationKey constructor that forces key to release its internal byte array for adoption. key will have a null byte array after this construction.

Parameters

source:String

string this CollationKey is to represent

key:RawCollationKey

RawCollationKey object that represents the collation order of argument source.

ICU Status

Stable since ICU 2.8.

See Also

Collator, RawCollationKey

Implements java.lang.Comparable.compareTo.

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

Parameters

target:CollationKey

target CollationKey

Returns:int

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.

Annotations

@Override

Exceptions

NullPointerException:

is thrown if argument is null.

ICU Status

Stable since ICU 2.8.

See Also

Collator#compare(String, String)

Overrides java.lang.Object.equals.

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.

Parameters

target:Object

the object to compare to.

Returns:boolean

true if the two keys compare as equal, false otherwise.

Annotations

@Override

Exceptions

ClassCastException:

is thrown when the argument is not a CollationKey. NullPointerException is thrown when the argument is null.

ICU Status

Stable since ICU 2.8.

See Also

compareTo(CollationKey)

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:CollationKey

the CollationKey to compare to.

Returns:boolean

true if two objects are equal, false otherwise.

Exceptions

NullPointerException:

is thrown when the argument is null.

ICU Status

Stable since ICU 2.8.

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.

Parameters

boundType:int

Mode of bound required. It can be BoundMode.LOWER, which produces a lower inclusive bound, BoundMode.UPPER, that produces upper bound that matches strings of the same length or BoundMode.UPPER_LONG that matches strings that have the same starting substring as the source string.

noOfLevels:int

Strength levels required in the resulting bound (for most uses, the recommended value is PRIMARY). This strength should be less than the maximum strength of this CollationKey. See users guide for explanation on the strength levels a collation key can have.

Returns:CollationKey

the result bounded CollationKey with a valid sort order but a null String representation.

Exceptions

IllegalArgumentException:

thrown when the strength level requested is higher than or equal to the strength in this CollationKey. In the case of an Exception, information about the maximum strength to use will be returned in the Exception. The user can then call getBound() again with the appropriate strength.

ICU Status

Stable since ICU 2.6.

See Also

CollationKey, CollationKey.BoundMode, Collator#PRIMARY, Collator#SECONDARY, Collator#TERTIARY, Collator#QUATERNARY, Collator#IDENTICAL

Return the source string that this CollationKey represents.

Returns:String

source string that this CollationKey represents

ICU Status

Stable since ICU 2.8.

Overrides java.lang.Object.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.

Returns:int

the hash value.

Annotations

@Override

ICU Status

Stable since ICU 2.8.

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 + '￾' + 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

Parameters

source:CollationKey

CollationKey to merge with

Returns:CollationKey

a CollationKey that contains the valid merged sort keys with a null String representation, i.e. new CollationKey(null, merged_sort_keys)

Exceptions

IllegalArgumentException:

thrown if source CollationKey argument is null or of 0 length.

ICU Status

Stable since ICU 2.6.

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:byte[]

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

ICU Status

Stable since ICU 2.8.