1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
/* * @(#)CollationKey.java 1.21 05/11/17 * * Copyright 2006 Sun Microsystems, Inc. All rights reserved. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ /* * (C) Copyright Taligent, Inc. 1996 - All Rights Reserved * (C) Copyright IBM Corp. 1996 - All Rights Reserved * * The original version of this source code and documentation is copyrighted * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These * materials are provided under terms of a License Agreement between Taligent * and Sun. This technology is protected by multiple US and International * patents. This notice and attribution to Taligent may not be removed. * Taligent is a registered trademark of Taligent, Inc. * */ package java.text; /** * A <code>CollationKey</code> represents a <code>String</code> under the * rules of a specific <code>Collator</code> object. Comparing two * <code>CollationKey</code>s returns the relative order of the * <code>String</code>s they represent. Using <code>CollationKey</code>s * to compare <code>String</code>s is generally faster than using * <code>Collator.compare</code>. Thus, when the <code>String</code>s * must be compared multiple times, for example when sorting a list * of <code>String</code>s. It's more efficient to use <code>CollationKey</code>s. * * <p> * You can not create <code>CollationKey</code>s directly. Rather, * generate them by calling <code>Collator.getCollationKey</code>. * You can only compare <code>CollationKey</code>s generated from * the same <code>Collator</code> object. * * <p> * Generating a <code>CollationKey</code> for a <code>String</code> * involves examining the entire <code>String</code> * and converting it to series of bits that can be compared bitwise. This * allows fast comparisons once the keys are generated. The cost of generating * keys is recouped in faster comparisons when <code>String</code>s need * to be compared many times. On the other hand, the result of a comparison * is often determined by the first couple of characters of each <code>String</code>. * <code>Collator.compare</code> examines only as many characters as it needs which * allows it to be faster when doing single comparisons. * <p> * The following example shows how <code>CollationKey</code>s might be used * to sort a list of <code>String</code>s. * <blockquote> * <pre> * // Create an array of CollationKeys for the Strings to be sorted. * Collator myCollator = Collator.getInstance(); * CollationKey[] keys = new CollationKey[3]; * keys[0] = myCollator.getCollationKey("Tom"); * keys[1] = myCollator.getCollationKey("Dick"); * keys[2] = myCollator.getCollationKey("Harry"); * sort( keys ); * <br> * //... * <br> * // Inside body of sort routine, compare keys this way * if( keys[i].compareTo( keys[j] ) > 0 ) * // swap keys[i] and keys[j] * <br> * //... * <br> * // Finally, when we've returned from sort. * System.out.println( keys[0].getSourceString() ); * System.out.println( keys[1].getSourceString() ); * System.out.println( keys[2].getSourceString() ); * </pre> * </blockquote> * * @see Collator * @see RuleBasedCollator * @version 1.21, 11/17/05 * @author Helena Shih */ public abstract class CollationKey implements Comparable<CollationKey> { /** * Compare this CollationKey to the target CollationKey. The collation rules of the * Collator object which created these keys are applied. <strong>Note:</strong> * CollationKeys created by different Collators can not be compared. * @param target target CollationKey * @return Returns an integer value. Value is less than zero if this is less * than target, value is zero if this and target are equal and value is greater than * zero if this is greater than target. * @see java.text.Collator#compare */ abstract public int compareTo(CollationKey target); /** * Returns the String that this CollationKey represents. */ public String getSourceString() { return source; } /** * Converts the CollationKey to a sequence of bits. If two CollationKeys * could be legitimately compared, then one could compare the byte arrays * for each of those keys to obtain the same result. Byte arrays are * organized most significant byte first. */ abstract public byte[] toByteArray(); /** * CollationKey constructor. * * @param source - the source string. * @exception NullPointerException if <code>source</code> is null. * @since 1.6 */ protected CollationKey(String source) { if (source==null){ throw new NullPointerException(); } this.source = source; } final private String source; }