A
CollationKey
represents a
String
under the rules of a specific
Collator
object. Comparing two
CollationKey
s returns the
relative order of the
String
s they represent.
Since the rule set of
Collator
s can differ, the
sort orders of the same string under two different
Collator
s might differ. Hence comparing
CollationKey
s generated from different
Collator
s 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
CollationKey
s can be used
to sort a list of
String
s.
// 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
compareTo
public int compareTo(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.
obj
- the Object to be compared to.
- Returns a negative integer, zero, or a positive integer
respectively if this CollationKey is less than, equal to, or
greater than the given Object.
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.
target
- target CollationKey
- 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.
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.
target
- the object to compare to.
- true if the two keys compare as equal, false otherwise.
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
target
- the CollationKey to compare to.
- true if two objects are equal, false otherwise.
getBound
public CollationKey getBound(int boundType,
int noOfLevels)
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.
boundType
- 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
- 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.
- the result bounded CollationKey with a valid sort order but
a null String representation.
getSourceString
public String getSourceString()
Return the source string that this CollationKey represents.
- 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. 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.
source
- CollationKey to merge with
- a CollationKey that contains the valid merged sorting order
with a null String representation,
i.e. new CollationKey(null, merge_sort_order)
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.");
- CollationKey value in a sequence of big-endian byte bytes
terminated by a null.