libcore/luni/src/main/java/java/text/CollationKey.java

   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 package java.text;
  19
  20 /**
  21  * Represents a string under the rules of a specific {@code Collator} object.
  22  * Comparing two {@code CollationKey} instances returns the relative order of
  23  * the strings they represent.
  24  * <p>
  25  * Since the rule set of collators can differ, the sort orders of the same
  26  * string under two different {@code Collator} instances might differ. Hence
  27  * comparing collation keys generated from different {@code Collator} instances
  28  * can give incorrect results.
  29  * <p>
  30  * Both the method {@code CollationKey.compareTo(CollationKey)} and the method
  31  * {@code Collator.compare(String, String)} compares two strings and returns
  32  * their relative order. The performance characteristics of these two approaches
  33  * can differ.
  34  * <p>
  35  * During the construction of a {@code CollationKey}, the entire source string
  36  * is examined and processed into a series of bits terminated by a null, that
  37  * are stored in the {@code CollationKey}. When
  38  * {@code CollationKey.compareTo(CollationKey)} executes, it performs bitwise
  39  * comparison on the bit sequences. This can incur startup cost when creating
  40  * the {@code CollationKey}, but once the key is created, binary comparisons
  41  * are fast. This approach is recommended when the same strings are to be
  42  * compared over and over again.
  43  * <p>
  44  * On the other hand, implementations of
  45  * {@code Collator.compare(String, String)} can examine and process the strings
  46  * only until the first characters differ in order. This approach is
  47  * recommended if the strings are to be compared only once.
  48  * <p>
  49  * The following example shows how collation keys can be used to sort a
  50  * list of strings:
  51  * <blockquote>
  52  *
  53  * <pre>
  54  * // Create an array of CollationKeys for the Strings to be sorted.
  55  * Collator myCollator = Collator.getInstance();
  56  * CollationKey[] keys = new CollationKey[3];
  57  * keys[0] = myCollator.getCollationKey(&quot;Tom&quot;);
  58  * keys[1] = myCollator.getCollationKey(&quot;Dick&quot;);
  59  * keys[2] = myCollator.getCollationKey(&quot;Harry&quot;);
  60  * sort(keys);
  61  * <br>
  62  * //...
  63  * <br>
  64  * // Inside body of sort routine, compare keys this way
  65  * if( keys[i].compareTo( keys[j] ) &gt; 0 )
  66  *    // swap keys[i] and keys[j]
  67  * <br>
  68  * //...
  69  * <br>
  70  * // Finally, when we've returned from sort.
  71  * System.out.println(keys[0].getSourceString());
  72  * System.out.println(keys[1].getSourceString());
  73  * System.out.println(keys[2].getSourceString());
  74  * </pre>
  75  *
  76  * </blockquote>
  77  *
  78  * @see Collator
  79  * @see RuleBasedCollator
  80  */
  81 public abstract class CollationKey implements Comparable<CollationKey> {
  82     private final String source;
  83
  84     protected CollationKey(String source) {
  85         this.source = source;
  86     }
  87
  88     /**
  89      * Compares this collation key to the given collation key.
  90      *
  91      * @param value the other collation key.
  92      * @return a negative value if this key is less than {@code value},
  93      *         0 if they are equal, and a positive value if this key is greater.
  94      */
  95     public abstract int compareTo(CollationKey value);
  96
  97     /**
  98      * Returns the string from which this collation key was created.
  99      *
 100      * @return the source string of this collation key.
 101      */
 102     public String getSourceString() {
 103         return source;
 104     }
 105
 106     /**
 107      * Returns this collation key as a byte array.
 108      *
 109      * @return an array of bytes.
 110      */
 111     public abstract byte[] toByteArray();
 112 }