jars/icu4j-4_2_1-src/src/com/ibm/icu/dev/eclipse/plugins/com.ibm.icu.base/src/com/ibm/icu/text/CollationKey.java

   1 /*\r
   2  *******************************************************************************\r
   3  * Copyright (C) 1996-2008, International Business Machines Corporation and    *\r
   4  * others. All Rights Reserved.                                                *\r
   5  *******************************************************************************\r
   6  */\r
   7 \r
   8 package com.ibm.icu.text;\r
   9 \r
  10 /**\r
  11  * <p>A <code>CollationKey</code> represents a <code>String</code>\r
  12  * under the rules of a specific <code>Collator</code>\r
  13  * object. Comparing two <code>CollationKey</code>s returns the\r
  14  * relative order of the <code>String</code>s they represent.</p>\r
  15  *\r
  16  * <p>Since the rule set of <code>Collator</code>s can differ, the\r
  17  * sort orders of the same string under two different\r
  18  * <code>Collator</code>s might differ.  Hence comparing\r
  19  * <code>CollationKey</code>s generated from different\r
  20  * <code>Collator</code>s can give incorrect results.</p>\r
  21  \r
  22  * <p>Both the method\r
  23  * <code>CollationKey.compareTo(CollationKey)</code> and the method\r
  24  * <code>Collator.compare(String, String)</code> compare two strings\r
  25  * and returns their relative order.  The performance characterictics\r
  26  * of these two approaches can differ.</p>\r
  27  *\r
  28  * <p>During the construction of a <code>CollationKey</code>, the\r
  29  * entire source string is examined and processed into a series of\r
  30  * bits terminated by a null, that are stored in the <code>CollationKey</code>. \r
  31  * When <code>CollationKey.compareTo(CollationKey)</code> executes, it\r
  32  * performs bitwise comparison on the bit sequences.  This can incurs\r
  33  * startup cost when creating the <code>CollationKey</code>, but once\r
  34  * the key is created, binary comparisons are fast.  This approach is\r
  35  * recommended when the same strings are to be compared over and over\r
  36  * again.</p>\r
  37  *\r
  38  * <p>On the other hand, implementations of\r
  39  * <code>Collator.compare(String, String)</code> can examine and\r
  40  * process the strings only until the first characters differing in\r
  41  * order.  This approach is recommended if the strings are to be\r
  42  * compared only once.</p>\r
  43  * \r
  44  * <p>More information about the composition of the bit sequence can\r
  45  * be found in the \r
  46  * <a href="http://www.icu-project.org/userguide/Collate_ServiceArchitecture.html">\r
  47  * user guide</a>.</p>\r
  48  *\r
  49  * <p>The following example shows how <code>CollationKey</code>s can be used\r
  50  * to sort a list of <code>String</code>s.</p>\r
  51  * <blockquote>\r
  52  * <pre>\r
  53  * // Create an array of CollationKeys for the Strings to be sorted.\r
  54  * Collator myCollator = Collator.getInstance();\r
  55  * CollationKey[] keys = new CollationKey[3];\r
  56  * keys[0] = myCollator.getCollationKey("Tom");\r
  57  * keys[1] = myCollator.getCollationKey("Dick");\r
  58  * keys[2] = myCollator.getCollationKey("Harry");\r
  59  * sort( keys );\r
  60  * <br>\r
  61  * //...\r
  62  * <br>\r
  63  * // Inside body of sort routine, compare keys this way\r
  64  * if( keys[i].compareTo( keys[j] ) > 0 )\r
  65  *    // swap keys[i] and keys[j]\r
  66  * <br>\r
  67  * //...\r
  68  * <br>\r
  69  * // Finally, when we've returned from sort.\r
  70  * System.out.println( keys[0].getSourceString() );\r
  71  * System.out.println( keys[1].getSourceString() );\r
  72  * System.out.println( keys[2].getSourceString() );\r
  73  * </pre>\r
  74  * </blockquote>\r
  75  * </p>\r
  76  * <p>\r
  77  * This class is not subclassable\r
  78  * </p>\r
  79  * @see Collator\r
  80  * @see RuleBasedCollator\r
  81  * @stable ICU 2.8 \r
  82  */\r
  83 public final class CollationKey implements Comparable {\r
  84     /**\r
  85      * @internal\r
  86      */\r
  87     final java.text.CollationKey key;\r
  88 \r
  89     /**\r
  90      * @internal\r
  91      */\r
  92     CollationKey(java.text.CollationKey delegate) {\r
  93         this.key = delegate;\r
  94     }\r
  95 \r
  96     /**\r
  97      * Return the source string that this CollationKey represents.\r
  98      * @return source string that this CollationKey represents\r
  99      * @stable ICU 2.8\r
 100      */\r
 101     public String getSourceString() {\r
 102         return key.getSourceString();\r
 103     }\r
 104     \r
 105     /**\r
 106      * <p>Duplicates and returns the value of this CollationKey as a sequence \r
 107      * of big-endian bytes terminated by a null.</p> \r
 108      *\r
 109      * <p>If two CollationKeys can be legitimately compared, then one can\r
 110      * compare the byte arrays of each to obtain the same result, e.g.\r
 111      * <pre>\r
 112      * byte key1[] = collationkey1.toByteArray();\r
 113      * byte key2[] = collationkey2.toByteArray();\r
 114      * int key, targetkey;\r
 115      * int i = 0;\r
 116      * do {\r
 117      *       key = key1[i] & 0xFF;\r
 118      *     targetkey = key2[i] & 0xFF;\r
 119      *     if (key &lt; targetkey) {\r
 120      *         System.out.println("String 1 is less than string 2");\r
 121      *         return;\r
 122      *     }\r
 123      *     if (targetkey &lt; key) {\r
 124      *         System.out.println("String 1 is more than string 2");\r
 125      *     }\r
 126      *     i ++;\r
 127      * } while (key != 0 && targetKey != 0);\r
 128      *\r
 129      * System.out.println("Strings are equal.");\r
 130      * </pre>\r
 131      * </p>  \r
 132      * @return CollationKey value in a sequence of big-endian byte bytes \r
 133      *         terminated by a null.\r
 134      * @stable ICU 2.8\r
 135      */\r
 136     public byte[] toByteArray() {\r
 137         return key.toByteArray();\r
 138     }\r
 139 \r
 140     /**\r
 141      * <p>Compare this CollationKey to another CollationKey.  The\r
 142      * collation rules of the Collator that created this key are\r
 143      * applied.</p>\r
 144      *\r
 145      * <p><strong>Note:</strong> Comparison between CollationKeys\r
 146      * created by different Collators might return incorrect\r
 147      * results.  See class documentation.</p>\r
 148      *\r
 149      * @param target target CollationKey\r
 150      * @return an integer value.  If the value is less than zero this CollationKey\r
 151      *         is less than than target, if the value is zero they are equal, and\r
 152      *         if the value is greater than zero this CollationKey is greater \r
 153      *         than target.\r
 154      * @exception NullPointerException is thrown if argument is null.\r
 155      * @see Collator#compare(String, String)\r
 156      * @stable ICU 2.8 \r
 157      */\r
 158     public int compareTo(CollationKey target) {\r
 159         return key.compareTo(target.key);\r
 160     }\r
 161 \r
 162     /**\r
 163      * <p>Compare this CollationKey with the specified Object.  The\r
 164      * collation rules of the Collator that created this key are\r
 165      * applied.</p>\r
 166      * \r
 167      * <p>See note in compareTo(CollationKey) for warnings about possible\r
 168      * incorrect results.</p>\r
 169      *\r
 170      * @param obj the Object to be compared to.\r
 171      * @return Returns a negative integer, zero, or a positive integer \r
 172      *         respectively if this CollationKey is less than, equal to, or \r
 173      *         greater than the given Object.\r
 174      * @exception ClassCastException is thrown when the argument is not \r
 175      *            a CollationKey.  NullPointerException is thrown when the argument \r
 176      *            is null.\r
 177      * @see #compareTo(CollationKey)\r
 178      * @stable ICU 2.8 \r
 179      */\r
 180     public int compareTo(Object o) {\r
 181         return compareTo((CollationKey)o);\r
 182     }\r
 183 \r
 184     /**\r
 185      * <p>Compare this CollationKey and the specified Object for\r
 186      * equality.  The collation rules of the Collator that created\r
 187      * this key are applied.</p>\r
 188      *\r
 189      * <p>See note in compareTo(CollationKey) for warnings about\r
 190      * possible incorrect results.</p>\r
 191      *\r
 192      * @param target the object to compare to.\r
 193      * @return true if the two keys compare as equal, false otherwise.\r
 194      * @see #compareTo(CollationKey)\r
 195      * @exception ClassCastException is thrown when the argument is not \r
 196      *            a CollationKey.  NullPointerException is thrown when the argument \r
 197      *            is null.\r
 198      * @stable ICU 2.8 \r
 199      */\r
 200     public boolean equals(Object target) {\r
 201         try {\r
 202             return key.equals(((CollationKey)target).key);\r
 203         }\r
 204         catch (Exception e) {\r
 205             return false;\r
 206         }\r
 207     }\r
 208 \r
 209     /**\r
 210      * <p>\r
 211      * Compare this CollationKey and the argument target CollationKey for \r
 212      * equality.\r
 213      * The collation \r
 214      * rules of the Collator object which created these objects are applied.\r
 215      * </p>\r
 216      * <p>\r
 217      * See note in compareTo(CollationKey) for warnings of incorrect results\r
 218      * </p>\r
 219      * @param target the CollationKey to compare to.\r
 220      * @return true if two objects are equal, false otherwise.\r
 221      * @exception NullPointerException is thrown when the argument is null.\r
 222      * @stable ICU 2.8\r
 223      */\r
 224     public boolean equals(CollationKey target) {\r
 225             return key.equals(target.key);\r
 226     }\r
 227     \r
 228     /**\r
 229      * <p>Returns a hash code for this CollationKey. The hash value is calculated \r
 230      * on the key itself, not the String from which the key was created. Thus \r
 231      * if x and y are CollationKeys, then x.hashCode(x) == y.hashCode() \r
 232      * if x.equals(y) is true. This allows language-sensitive comparison in a \r
 233      * hash table.\r
 234      * </p>\r
 235      * @return the hash value.\r
 236      * @stable ICU 2.8\r
 237      */\r
 238     public int hashCode() {\r
 239         return key.hashCode();\r
 240     }\r
 241 \r
 242     /**\r
 243      * Return a description of the CollationKey.\r
 244      * @return a description of the CollationKey, used for debugging\r
 245      * @stable ICU 3.4.2\r
 246      */\r
 247     public String toString() {\r
 248         return key.toString();\r
 249     }\r
 250 }\r