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 &lt; 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 &lt; 0, or size &gt; 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