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("Tom"); 61 * keys[1] = myCollator.getCollationKey("Dick"); 62 * keys[2] = myCollator.getCollationKey("Harry"); 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] ) > 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