1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18// BEGIN android-note
19// The icu implementation used was changed from icu4j to icu4jni.
20// END android-note
21
22package java.text;
23/**
24 * Represents a string under the rules of a specific {@code Collator} object.
25 * Comparing two {@code CollationKey} instances returns the relative order of
26 * the strings they represent.
27 * <p>
28 * Since the rule set of collators can differ, the sort orders of the same
29 * string under two different {@code Collator} instances might differ. Hence
30 * comparing collation keys generated from different {@code Collator} instances
31 * can give incorrect results.
32 * <p>
33 * Both the method {@code CollationKey.compareTo(CollationKey)} and the method
34 * {@code Collator.compare(String, String)} compares two strings and returns
35 * their relative order. The performance characteristics of these two approaches
36 * can differ.
37 * <p>
38 * During the construction of a {@code CollationKey}, the entire source string
39 * is examined and processed into a series of bits terminated by a null, that
40 * are stored in the {@code CollationKey}. When
41 * {@code CollationKey.compareTo(CollationKey)} executes, it performs bitwise
42 * comparison on the bit sequences. This can incur startup cost when creating
43 * the {@code CollationKey}, but once the key is created, binary comparisons
44 * are fast. This approach is recommended when the same strings are to be
45 * compared over and over again.
46 * <p>
47 * On the other hand, implementations of
48 * {@code Collator.compare(String, String)} can examine and process the strings
49 * only until the first characters differ in order. This approach is
50 * recommended if the strings are to be compared only once.
51 * <p>
52 * The following example shows how collation keys can be used to sort a
53 * list of strings:
54 * <blockquote>
55 *
56 * <pre>
57 * // Create an array of CollationKeys for the Strings to be sorted.
58 * Collator myCollator = Collator.getInstance();
59 * CollationKey[] keys = new CollationKey[3];
60 * keys[0] = myCollator.getCollationKey(&quot;Tom&quot;);
61 * keys[1] = myCollator.getCollationKey(&quot;Dick&quot;);
62 * keys[2] = myCollator.getCollationKey(&quot;Harry&quot;);
63 * sort(keys);
64 * <br>
65 * //...
66 * <br>
67 * // Inside body of sort routine, compare keys this way
68 * if( keys[i].compareTo( keys[j] ) &gt; 0 )
69 *    // swap keys[i] and keys[j]
70 * <br>
71 * //...
72 * <br>
73 * // Finally, when we've returned from sort.
74 * System.out.println(keys[0].getSourceString());
75 * System.out.println(keys[1].getSourceString());
76 * System.out.println(keys[2].getSourceString());
77 * </pre>
78 *
79 * </blockquote>
80 *
81 * @see Collator
82 * @see RuleBasedCollator
83 */
84public final class CollationKey implements Comparable<CollationKey> {
85
86    private String source;
87
88    private com.ibm.icu4jni.text.CollationKey icuKey;
89
90    CollationKey(String source, com.ibm.icu4jni.text.CollationKey key) {
91        this.source = source;
92        this.icuKey = key;
93    }
94
95    /**
96     * Compares this object to the specified collation key object to determine
97     * their relative order.
98     *
99     * @param value
100     *            the collation key object to compare this object to.
101     * @return a negative value if this {@code CollationKey} is less than the
102     *         specified {@code CollationKey}, 0 if they are equal and a
103     *         positive value if this {@code CollationKey} is greater.
104     */
105    public int compareTo(CollationKey value) {
106        return icuKey.compareTo(value.icuKey);
107    }
108
109    /**
110     * Compares the specified object to this {@code CollationKey} and indicates
111     * if they are equal. The object must be an instance of {@code CollationKey}
112     * and have the same source string and collation key. Both instances of
113     * {@code CollationKey} must have been created by the same {@code Collator}.
114     *
115     * @param object
116     *            the object to compare to this object.
117     * @return {@code true} if {@code object} is equal to this collation key;
118     *         {@code false} otherwise.
119     * @see #hashCode
120     */
121    @Override
122    public boolean equals(Object object) {
123        if (!(object instanceof CollationKey)) {
124            return false;
125        }
126        CollationKey collationKey = (CollationKey) object;
127        return icuKey.equals(collationKey.icuKey);
128    }
129
130    /**
131     * Returns the string from which this collation key was created.
132     *
133     * @return the source string of this collation key.
134     */
135    public String getSourceString() {
136        return this.source;
137    }
138
139    /**
140     * Returns an integer hash code for the receiver. Objects which are equal
141     * return the same value for this method.
142     *
143     * @return the receiver's hash.
144     *
145     * @see #equals
146     */
147    @Override
148    public int hashCode() {
149        return icuKey.hashCode();
150    }
151
152    /**
153     * Returns the collation key as a byte array.
154     *
155     * @return an array of bytes.
156     */
157    public byte[] toByteArray() {
158        return icuKey.toByteArray();
159    }
160}
161