| /** |
| ******************************************************************************* |
| * Copyright (C) 1996-2011, International Business Machines Corporation and * |
| * others. All Rights Reserved. * |
| ******************************************************************************* |
| */ |
| package com.ibm.icu.text; |
| |
| /** |
| * <p>A <code>CollationKey</code> represents a <code>String</code> |
| * under the rules of a specific <code>Collator</code> |
| * object. Comparing two <code>CollationKey</code>s returns the |
| * relative order of the <code>String</code>s they represent.</p> |
| * |
| * <p>Since the rule set of <code>Collator</code>s can differ, the |
| * sort orders of the same string under two different |
| * <code>Collator</code>s might differ. Hence comparing |
| * <code>CollationKey</code>s generated from different |
| * <code>Collator</code>s can give incorrect results.</p> |
| |
| * <p>Both the method |
| * <code>CollationKey.compareTo(CollationKey)</code> and the method |
| * <code>Collator.compare(String, String)</code> compare two strings |
| * and returns their relative order. The performance characterictics |
| * of these two approaches can differ.</p> |
| * |
| * <p>During the construction of a <code>CollationKey</code>, the |
| * entire source string is examined and processed into a series of |
| * bits terminated by a null, that are stored in the <code>CollationKey</code>. |
| * When <code>CollationKey.compareTo(CollationKey)</code> executes, it |
| * performs bitwise comparison on the bit sequences. This can incurs |
| * startup cost when creating the <code>CollationKey</code>, 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.</p> |
| * |
| * <p>On the other hand, implementations of |
| * <code>Collator.compare(String, String)</code> 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.</p> |
| * |
| * <p>More information about the composition of the bit sequence can |
| * be found in the |
| * <a href="http://www.icu-project.org/userguide/Collate_ServiceArchitecture.html"> |
| * user guide</a>.</p> |
| * |
| * <p>The following example shows how <code>CollationKey</code>s can be used |
| * to sort a list of <code>String</code>s.</p> |
| * <blockquote> |
| * <pre> |
| * // 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 ); |
| * <br> |
| * //... |
| * <br> |
| * // Inside body of sort routine, compare keys this way |
| * if( keys[i].compareTo( keys[j] ) > 0 ) |
| * // swap keys[i] and keys[j] |
| * <br> |
| * //... |
| * <br> |
| * // 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() ); |
| * </pre> |
| * </blockquote> |
| * </p> |
| * <p> |
| * This class is not subclassable |
| * </p> |
| * @see Collator |
| * @see RuleBasedCollator |
| * @author Syn Wee Quek |
| * @stable ICU 2.8 |
| */ |
| public final class CollationKey implements Comparable<CollationKey> |
| { |
| /** |
| * @internal |
| */ |
| final java.text.CollationKey key; |
| |
| /** |
| * @internal |
| */ |
| CollationKey(java.text.CollationKey delegate) { |
| this.key = delegate; |
| } |
| |
| // public inner classes ------------------------------------------------- |
| |
| /** |
| * Options that used in the API CollationKey.getBound() for getting a |
| * CollationKey based on the bound mode requested. |
| * @stable ICU 2.6 |
| */ |
| public static final class BoundMode |
| { |
| /* |
| * do not change the values assigned to the members of this enum. |
| * Underlying code depends on them having these numbers |
| */ |
| |
| /** |
| * Lower bound |
| * @stable ICU 2.6 |
| */ |
| public static final int LOWER = 0; |
| |
| /** |
| * Upper bound that will match strings of exact size |
| * @stable ICU 2.6 |
| */ |
| public static final int UPPER = 1; |
| |
| /** |
| * Upper bound that will match all the strings that have the same |
| * initial substring as the given string |
| * @stable ICU 2.6 |
| */ |
| public static final int UPPER_LONG = 2; |
| |
| /** |
| * Number of bound mode |
| * @stable ICU 2.6 |
| */ |
| public static final int COUNT = 3; |
| |
| /** |
| * Private Constructor |
| */ |
| ///CLOVER:OFF |
| private BoundMode(){} |
| ///CLOVER:ON |
| } |
| |
| // public constructor --------------------------------------------------- |
| |
| /** |
| * CollationKey constructor. |
| * This constructor is given public access, unlike the JDK version, to |
| * allow access to users extending the Collator class. See |
| * {@link Collator#getCollationKey(String)}. |
| * @param source string this CollationKey is to represent |
| * @param key array of bytes that represent the collation order of argument |
| * source terminated by a null |
| * @see Collator |
| * @stable ICU 2.8 |
| */ |
| public CollationKey(String source, byte key[]) |
| { |
| throw new UnsupportedOperationException("Constructor not supported by com.ibm.icu.base"); |
| } |
| |
| /** |
| * CollationKey constructor that forces key to release its internal byte |
| * array for adoption. key will have a null byte array after this |
| * construction. |
| * @param source string this CollationKey is to represent |
| * @param key RawCollationKey object that represents the collation order of |
| * argument source. |
| * @see Collator |
| * @see RawCollationKey |
| * @stable ICU 2.8 |
| */ |
| public CollationKey(String source, RawCollationKey key) |
| { |
| throw new UnsupportedOperationException("Constructor not supported by com.ibm.icu.base"); |
| } |
| |
| // public getters ------------------------------------------------------- |
| |
| /** |
| * Return the source string that this CollationKey represents. |
| * @return source string that this CollationKey represents |
| * @stable ICU 2.8 |
| */ |
| public String getSourceString() |
| { |
| return key.getSourceString(); |
| } |
| |
| /** |
| * <p>Duplicates and returns the value of this CollationKey as a sequence |
| * of big-endian bytes terminated by a null.</p> |
| * |
| * <p>If two CollationKeys can be legitimately compared, then one can |
| * compare the byte arrays of each to obtain the same result, e.g. |
| * <pre> |
| * 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."); |
| * </pre> |
| * </p> |
| * @return CollationKey value in a sequence of big-endian byte bytes |
| * terminated by a null. |
| * @stable ICU 2.8 |
| */ |
| public byte[] toByteArray() |
| { |
| return key.toByteArray(); |
| } |
| |
| // public other methods ------------------------------------------------- |
| |
| /** |
| * <p>Compare this CollationKey to another CollationKey. The |
| * collation rules of the Collator that created this key are |
| * applied.</p> |
| * |
| * <p><strong>Note:</strong> Comparison between CollationKeys |
| * created by different Collators might return incorrect |
| * results. See class documentation.</p> |
| * |
| * @param target target CollationKey |
| * @return 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. |
| * @exception NullPointerException is thrown if argument is null. |
| * @see Collator#compare(String, String) |
| * @stable ICU 2.8 |
| */ |
| public int compareTo(CollationKey target) |
| { |
| return key.compareTo(target.key); |
| } |
| |
| /** |
| * <p>Compare this CollationKey and the specified Object for |
| * equality. The collation rules of the Collator that created |
| * this key are applied.</p> |
| * |
| * <p>See note in compareTo(CollationKey) for warnings about |
| * possible incorrect results.</p> |
| * |
| * @param target the object to compare to. |
| * @return true if the two keys compare as equal, false otherwise. |
| * @see #compareTo(CollationKey) |
| * @exception ClassCastException is thrown when the argument is not |
| * a CollationKey. NullPointerException is thrown when the argument |
| * is null. |
| * @stable ICU 2.8 |
| */ |
| public boolean equals(Object target) |
| { |
| if (!(target instanceof CollationKey)) { |
| return false; |
| } |
| |
| return equals((CollationKey)target); |
| } |
| |
| /** |
| * <p> |
| * Compare this CollationKey and the argument target CollationKey for |
| * equality. |
| * The collation |
| * rules of the Collator object which created these objects are applied. |
| * </p> |
| * <p> |
| * See note in compareTo(CollationKey) for warnings of incorrect results |
| * </p> |
| * @param target the CollationKey to compare to. |
| * @return true if two objects are equal, false otherwise. |
| * @exception NullPointerException is thrown when the argument is null. |
| * @stable ICU 2.8 |
| */ |
| public boolean equals(CollationKey target) |
| { |
| return key.equals(target.key); |
| } |
| |
| /** |
| * <p>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. |
| * </p> |
| * @return the hash value. |
| * @stable ICU 2.8 |
| */ |
| public int hashCode() |
| { |
| return key.hashCode(); |
| } |
| |
| /** |
| * <p> |
| * 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. |
| * </p> |
| * <p> |
| * 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". |
| * </p> |
| * <p> |
| * 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. |
| * </p> |
| * <p> |
| * For more on usage, see example in test procedure |
| * <a href="http://source.icu-project.org/repos/icu/icu4j/trunk/src/com/ibm/icu/dev/test/collator/CollationAPITest.java"> |
| * src/com/ibm/icu/dev/test/collator/CollationAPITest/TestBounds. |
| * </a> |
| * </p> |
| * <p> |
| * Collation keys produced may be compared using the <TT>compare</TT> API. |
| * </p> |
| * @param 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. |
| * @param 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. |
| * @return the result bounded CollationKey with a valid sort order but |
| * a null String representation. |
| * @exception 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. |
| * @see CollationKey |
| * @see CollationKey.BoundMode |
| * @see Collator#PRIMARY |
| * @see Collator#SECONDARY |
| * @see Collator#TERTIARY |
| * @see Collator#QUATERNARY |
| * @see Collator#IDENTICAL |
| * @stable ICU 2.6 |
| */ |
| public CollationKey getBound(int boundType, int noOfLevels) |
| { |
| throw new UnsupportedOperationException("Method not supported by com.ibm.icu.base"); |
| } |
| |
| /** |
| * <p> |
| * 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. |
| * </p> |
| * <p> |
| * The strength levels are merged with their corresponding counterparts |
| * (PRIMARIES with PRIMARIES, SECONDARIES with SECONDARIES etc.). |
| * </p> |
| * <p> |
| * The merged String representation of the result CollationKey will be a |
| * concatenation of the String representations of the 2 source |
| * CollationKeys. |
| * </p> |
| * <p> |
| * Between the values from the same level a separator is inserted. |
| * example (uncompressed): |
| * <pre> |
| * 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 |
| * </pre> |
| * </p> |
| * <p> |
| * This allows for concatenating of first and last names for sorting, among |
| * other things. |
| * </p> |
| * </p> |
| * @param source CollationKey to merge with |
| * @return a CollationKey that contains the valid merged sorting order |
| * with a null String representation, |
| * i.e. <tt>new CollationKey(null, merge_sort_order)</tt> |
| * @exception IllegalArgumentException thrown if source CollationKey |
| * argument is null or of 0 length. |
| * @stable ICU 2.6 |
| */ |
| public CollationKey merge(CollationKey source) |
| { |
| throw new UnsupportedOperationException("Method not supported by com.ibm.icu.base"); |
| } |
| } |
