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