001: /*
002: *
003: * @(#)CollationKey.java 1.21 06/10/10
004: *
005: * Portions Copyright 2000-2006 Sun Microsystems, Inc. All Rights
006: * Reserved. Use is subject to license terms.
007: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
008: *
009: * This program is free software; you can redistribute it and/or
010: * modify it under the terms of the GNU General Public License version
011: * 2 only, as published by the Free Software Foundation.
012: *
013: * This program is distributed in the hope that it will be useful, but
014: * WITHOUT ANY WARRANTY; without even the implied warranty of
015: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
016: * General Public License version 2 for more details (a copy is
017: * included at /legal/license.txt).
018: *
019: * You should have received a copy of the GNU General Public License
020: * version 2 along with this work; if not, write to the Free Software
021: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
022: * 02110-1301 USA
023: *
024: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
025: * Clara, CA 95054 or visit www.sun.com if you need additional
026: * information or have any questions.
027: */
028:
029: /*
030: * (C) Copyright Taligent, Inc. 1996 - All Rights Reserved
031: * (C) Copyright IBM Corp. 1996 - All Rights Reserved
032: *
033: * The original version of this source code and documentation is copyrighted
034: * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
035: * materials are provided under terms of a License Agreement between Taligent
036: * and Sun. This technology is protected by multiple US and International
037: * patents. This notice and attribution to Taligent may not be removed.
038: * Taligent is a registered trademark of Taligent, Inc.
039: *
040: */
041:
042: package java.text;
043:
044: /**
045: * A <code>CollationKey</code> represents a <code>String</code> under the
046: * rules of a specific <code>Collator</code> object. Comparing two
047: * <code>CollationKey</code>s returns the relative order of the
048: * <code>String</code>s they represent. Using <code>CollationKey</code>s
049: * to compare <code>String</code>s is generally faster than using
050: * <code>Collator.compare</code>. Thus, when the <code>String</code>s
051: * must be compared multiple times, for example when sorting a list
052: * of <code>String</code>s. It's more efficient to use <code>CollationKey</code>s.
053: *
054: * <p>
055: * You can not create <code>CollationKey</code>s directly. Rather,
056: * generate them by calling <code>Collator.getCollationKey</code>.
057: * You can only compare <code>CollationKey</code>s generated from
058: * the same <code>Collator</code> object.
059: *
060: * <p>
061: * Generating a <code>CollationKey</code> for a <code>String</code>
062: * involves examining the entire <code>String</code>
063: * and converting it to series of bits that can be compared bitwise. This
064: * allows fast comparisons once the keys are generated. The cost of generating
065: * keys is recouped in faster comparisons when <code>String</code>s need
066: * to be compared many times. On the other hand, the result of a comparison
067: * is often determined by the first couple of characters of each <code>String</code>.
068: * <code>Collator.compare</code> examines only as many characters as it needs which
069: * allows it to be faster when doing single comparisons.
070: * <p>
071: * The following example shows how <code>CollationKey</code>s might be used
072: * to sort a list of <code>String</code>s.
073: * <blockquote>
074: * <pre>
075: * // Create an array of CollationKeys for the Strings to be sorted.
076: * Collator myCollator = Collator.getInstance();
077: * CollationKey[] keys = new CollationKey[3];
078: * keys[0] = myCollator.getCollationKey("Tom");
079: * keys[1] = myCollator.getCollationKey("Dick");
080: * keys[2] = myCollator.getCollationKey("Harry");
081: * sort( keys );
082: * <br>
083: * //...
084: * <br>
085: * // Inside body of sort routine, compare keys this way
086: * if( keys[i].compareTo( keys[j] ) > 0 )
087: * // swap keys[i] and keys[j]
088: * <br>
089: * //...
090: * <br>
091: * // Finally, when we've returned from sort.
092: * System.out.println( keys[0].getSourceString() );
093: * System.out.println( keys[1].getSourceString() );
094: * System.out.println( keys[2].getSourceString() );
095: * </pre>
096: * </blockquote>
097: *
098: * @see Collator
099: * @see RuleBasedCollator
100: * @version 1.14, 01/19/00
101: * @author Helena Shih
102: */
103:
104: public final class CollationKey implements Comparable {
105: /**
106: * Compare this CollationKey to the target CollationKey. The collation rules of the
107: * Collator object which created these keys are applied. <strong>Note:</strong>
108: * CollationKeys created by different Collators can not be compared.
109: * @param target target CollationKey
110: * @return Returns an integer value. Value is less than zero if this is less
111: * than target, value is zero if this and target are equal and value is greater than
112: * zero if this is greater than target.
113: * @see java.text.Collator#compare
114: */
115: public int compareTo(CollationKey target) {
116: int result = key.compareTo(target.key);
117: if (result <= Collator.LESS)
118: return Collator.LESS;
119: else if (result >= Collator.GREATER)
120: return Collator.GREATER;
121: return Collator.EQUAL;
122: }
123:
124: /**
125: * Compares this CollationKey with the specified Object for order. Returns
126: * a negative integer, zero, or a positive integer as this CollationKey
127: * is less than, equal to, or greater than the given Object.
128: *
129: * @param o the Object to be compared.
130: * @return a negative integer, zero, or a positive integer as this
131: * Collation Key is less than, equal to, or greater than the given
132: * Object.
133: * @exception ClassCastException the specified Object is not a
134: * CollationKey.
135: * @see Comparable
136: * @since 1.2
137: */
138: public int compareTo(Object o) {
139: return compareTo((CollationKey) o);
140: }
141:
142: /**
143: * Compare this CollationKey and the target CollationKey for equality.
144: * The collation rules of the Collator object which created these keys are applied.
145: * <strong>Note:</strong> CollationKeys created by different Collators can not be
146: * compared.
147: * @param target the CollationKey to compare to.
148: * @return Returns true if two objects are equal, false otherwise.
149: */
150: public boolean equals(Object target) {
151: if (this == target)
152: return true;
153: if (target == null || !getClass().equals(target.getClass())) {
154: return false;
155: }
156: CollationKey other = (CollationKey) target;
157: return key.equals(other.key);
158: }
159:
160: /**
161: * Creates a hash code for this CollationKey. The hash value is calculated on the
162: * key itself, not the String from which the key was created. Thus
163: * if x and y are CollationKeys, then x.hashCode(x) == y.hashCode() if
164: * x.equals(y) is true. This allows language-sensitive comparison in a hash table.
165: * See the CollatinKey class description for an example.
166: * @return the hash value based on the string's collation order.
167: */
168: public int hashCode() {
169: return (key.hashCode());
170: }
171:
172: /**
173: * Returns the String that this CollationKey represents.
174: */
175: public String getSourceString() {
176: return source;
177: }
178:
179: /**
180: * Converts the CollationKey to a sequence of bits. If two CollationKeys
181: * could be legitimately compared, then one could compare the byte arrays
182: * for each of those keys to obtain the same result. Byte arrays are
183: * organized most significant byte first.
184: */
185: public byte[] toByteArray() {
186:
187: char[] src = key.toCharArray();
188: byte[] dest = new byte[2 * src.length];
189: int j = 0;
190: for (int i = 0; i < src.length; i++) {
191: dest[j++] = (byte) (src[i] >>> 8);
192: dest[j++] = (byte) (src[i] & 0x00ff);
193: }
194: return dest;
195: }
196:
197: /**
198: * A CollationKey can only be generated by Collator objects.
199: */
200: CollationKey(String source, String key) {
201: this .source = source;
202: this .key = key;
203: }
204:
205: private String source = null;
206: private String key = null;
207: }
|