CollationKey


1   /*
2    * @(#)CollationKey.java    1.18 04/05/05
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   /*
9    * (C) Copyright Taligent, Inc. 1996 - All Rights Reserved
10   * (C) Copyright IBM Corp. 1996 - All Rights Reserved
11   *
12   *   The original version of this source code and documentation is copyrighted
13   * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
14   * materials are provided under terms of a License Agreement between Taligent
15   * and Sun. This technology is protected by multiple US and International
16   * patents. This notice and attribution to Taligent may not be removed.
17   *   Taligent is a registered trademark of Taligent, Inc.
18   *
19   */
20  
21  package java.text;
22  
23  /**
24   * A <code>CollationKey</code> represents a <code>String</code> under the
25   * rules of a specific <code>Collator</code> object. Comparing two
26   * <code>CollationKey</code>s returns the relative order of the
27   * <code>String</code>s they represent. Using <code>CollationKey</code>s
28   * to compare <code>String</code>s is generally faster than using
29   * <code>Collator.compare</code>. Thus, when the <code>String</code>s
30   * must be compared multiple times, for example when sorting a list
31   * of <code>String</code>s. It's more efficient to use <code>CollationKey</code>s.
32   *
33   * <p>
34   * You can not create <code>CollationKey</code>s directly. Rather,
35   * generate them by calling <code>Collator.getCollationKey</code>.
36   * You can only compare <code>CollationKey</code>s generated from
37   * the same <code>Collator</code> object.
38   *
39   * <p>
40   * Generating a <code>CollationKey</code> for a <code>String</code>
41   * involves examining the entire <code>String</code>
42   * and converting it to series of bits that can be compared bitwise. This
43   * allows fast comparisons once the keys are generated. The cost of generating
44   * keys is recouped in faster comparisons when <code>String</code>s need
45   * to be compared many times. On the other hand, the result of a comparison
46   * is often determined by the first couple of characters of each <code>String</code>.
47   * <code>Collator.compare</code> examines only as many characters as it needs which
48   * allows it to be faster when doing single comparisons.
49   * <p>
50   * The following example shows how <code>CollationKey</code>s might be used
51   * to sort a list of <code>String</code>s.
52   * <blockquote>
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("Tom");
58   * keys[1] = myCollator.getCollationKey("Dick");
59   * keys[2] = myCollator.getCollationKey("Harry");
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] ) > 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   * </blockquote>
76   *
77   * @see          Collator
78   * @see          RuleBasedCollator
79   * @version      1.18, 05/05/04
80   * @author       Helena Shih
81   */
82  
83  public final class CollationKey implements Comparable  <CollationKey  > {
84      /**
85       * Compare this CollationKey to the target CollationKey. The collation rules of the
86       * Collator object which created these keys are applied. <strong>Note:</strong>
87       * CollationKeys created by different Collators can not be compared.
88       * @param target target CollationKey
89       * @return Returns an integer value. Value is less than zero if this is less
90       * than target, value is zero if this and target are equal and value is greater than
91       * zero if this is greater than target.
92       * @see java.text.Collator#compare
93       */
94      public int compareTo(CollationKey   target)
95      {
96          int result = key.compareTo(target.key);
97          if (result <= Collator.LESS)
98              return Collator.LESS;
99          else if (result >= Collator.GREATER)
100             return Collator.GREATER;
101         return Collator.EQUAL;
102     }
103 
104     /**
105      * Compare this CollationKey and the target CollationKey for equality.
106      * The collation rules of the Collator object which created these keys are applied.
107      * <strong>Note:</strong> CollationKeys created by different Collators can not be
108      * compared.
109      * @param target the CollationKey to compare to.
110      * @return Returns true if two objects are equal, false otherwise.
111      */
112     public boolean equals(Object   target) {
113         if (this == target) return true;
114         if (target == null || !getClass().equals(target.getClass())) {
115             return false;
116         }
117         CollationKey   other = (CollationKey  )target;
118         return key.equals(other.key);
119     }
120 
121     /**
122      * Creates a hash code for this CollationKey. The hash value is calculated on the
123      * key itself, not the String from which the key was created.  Thus
124      * if x and y are CollationKeys, then x.hashCode(x) == y.hashCode() if
125      * x.equals(y) is true.  This allows language-sensitive comparison in a hash table.
126      * See the CollatinKey class description for an example.
127      * @return the hash value based on the string's collation order.
128      */
129     public int hashCode() {
130         return (key.hashCode());
131     }
132 
133 
134     /**
135      * Returns the String that this CollationKey represents.
136      */
137     public String   getSourceString() {
138         return source;
139     }
140 
141 
142     /**
143      * Converts the CollationKey to a sequence of bits. If two CollationKeys
144      * could be legitimately compared, then one could compare the byte arrays
145      * for each of those keys to obtain the same result.  Byte arrays are
146      * organized most significant byte first.
147      */
148     public byte[] toByteArray() {
149 
150         char[] src = key.toCharArray();
151         byte[] dest = new byte[ 2*src.length ];
152         int j = 0;
153         for( int i=0; i<src.length; i++ ) {
154             dest[j++] = (byte)(src[i] >>> 8);
155             dest[j++] = (byte)(src[i] & 0x00ff);
156         }
157         return dest;
158     }
159 
160     /**
161      * A CollationKey can only be generated by Collator objects.
162      */
163     CollationKey(String   source, String   key) {
164         this.source = source;
165         this.key = key;
166     }
167 
168     private String   source = null;
169     private String   key = null;
170 }
171 
172 
173 
174
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags