jars/icu4j-4_4_2-src/main/classes/collate/src/com/ibm/icu/text/RawCollationKey.java

   1 /**\r
   2  *******************************************************************************\r
   3  * Copyright (C) 1996-2010, 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 import com.ibm.icu.util.ByteArrayWrapper;\r
  11 \r
  12 /**\r
  13  * <p>\r
  14  * Simple class wrapper to store the internal byte representation of a \r
  15  * CollationKey. Unlike the CollationKey, this class do not contain information \r
  16  * on the source string the sort order represents. RawCollationKey is mutable \r
  17  * and users can reuse its objects with the method in \r
  18  * RuleBasedCollator.getRawCollationKey(..).\r
  19  * </p>\r
  20  * <p>\r
  21  * Please refer to the documentation on CollationKey for a detail description\r
  22  * on the internal byte representation. Note the internal byte representation \r
  23  * is always null-terminated.\r
  24  * </p> \r
  25  * <code>\r
  26  * Example of use:<br>\r
  27  * String str[] = {.....};\r
  28  * RuleBasedCollator collator = (RuleBasedCollator)Collator.getInstance();\r
  29  * RawCollationKey key = new RawCollationKey(128);\r
  30  * for (int i = 0; i &lt; str.length; i ++) {\r
  31  *     collator.getRawCollationKey(str[i], key);\r
  32  *     // do something with key.bytes\r
  33  * }\r
  34  * </code>\r
  35  * <p><strong>Note:</strong> Comparison between RawCollationKeys created by \r
  36  * different Collators might return incorrect results.  \r
  37  * See class documentation for Collator.</p>\r
  38  * @stable ICU 2.8\r
  39  * @see RuleBasedCollator\r
  40  * @see CollationKey\r
  41  */\r
  42 public final class RawCollationKey extends ByteArrayWrapper\r
  43 {\r
  44     // public constructors --------------------------------------------------\r
  45     \r
  46     /**\r
  47      * Default constructor, internal byte array is null and its size set to 0.\r
  48      * @stable ICU 2.8\r
  49      */\r
  50     public RawCollationKey() \r
  51     {\r
  52     }\r
  53 \r
  54     /**\r
  55      * RawCollationKey created with an empty internal byte array of length \r
  56      * capacity. Size of the internal byte array will be set to 0.\r
  57      * @param capacity length of internal byte array\r
  58      * @stable ICU 2.8\r
  59      */\r
  60     public RawCollationKey(int capacity) \r
  61     {\r
  62         bytes = new byte[capacity];\r
  63     }\r
  64 \r
  65     /**\r
  66      * RawCollationKey created, adopting bytes as the internal byte array.\r
  67      * Size of the internal byte array will be set to 0.\r
  68      * @param bytes byte array to be adopted by RawCollationKey\r
  69      * @stable ICU 2.8\r
  70      */\r
  71     public RawCollationKey(byte[] bytes) \r
  72     {\r
  73         this.bytes = bytes;\r
  74     }\r
  75     \r
  76     /**\r
  77      * Construct a RawCollationKey from a byte array and size.\r
  78      * @param bytesToAdopt the byte array to adopt\r
  79      * @param size the length of valid data in the byte array\r
  80      * @throws IndexOutOfBoundsException if bytesToAdopt == null and size != 0, or\r
  81      * size < 0, or size > bytesToAdopt.length.\r
  82      * @stable ICU 2.8\r
  83      */\r
  84     public RawCollationKey(byte[] bytesToAdopt, int size) \r
  85     {\r
  86         super(bytesToAdopt, size);\r
  87     }\r
  88 \r
  89     /**\r
  90      * Compare this RawCollationKey to another, which must not be null.  This overrides\r
  91      * the inherited implementation to ensure the returned values are -1, 0, or 1.\r
  92      * @param rhs the RawCollationKey to compare to.\r
  93      * @return -1, 0, or 1 as this compares less than, equal to, or\r
  94      * greater than rhs.\r
  95      * @throws ClassCastException if the other object is not a RawCollationKey.\r
  96      * @stable ICU 4.4\r
  97      */\r
  98     public int compareTo(RawCollationKey rhs) {\r
  99         int result = super.compareTo(rhs);\r
 100         return result < 0 ? -1 : result == 0 ? 0 : 1;\r
 101     }\r
 102 }\r