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