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