1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved. 4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 * 6 * This code is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License version 2 only, as 8 * published by the Free Software Foundation. Oracle designates this 9 * particular file as subject to the "Classpath" exception as provided 10 * by Oracle in the LICENSE file that accompanied this code. 11 * 12 * This code is distributed in the hope that it will be useful, but WITHOUT 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 * version 2 for more details (a copy is included in the LICENSE file that 16 * accompanied this code). 17 * 18 * You should have received a copy of the GNU General Public License version 19 * 2 along with this work; if not, write to the Free Software Foundation, 20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 * 22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 * or visit www.oracle.com if you need additional information or have any 24 * questions. 25 */ 26 27 /* 28 * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved 29 * (C) Copyright IBM Corp. 1996-1998 - All Rights Reserved 30 * 31 * The original version of this source code and documentation is copyrighted 32 * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These 33 * materials are provided under terms of a License Agreement between Taligent 34 * and Sun. This technology is protected by multiple US and International 35 * patents. This notice and attribution to Taligent may not be removed. 36 * Taligent is a registered trademark of Taligent, Inc. 37 * 38 */ 39 40 package java.text; 41 42 /** 43 * The <code>CollationElementIterator</code> class is used as an iterator 44 * to walk through each character of an international string. Use the iterator 45 * to return the ordering priority of the positioned character. The ordering 46 * priority of a character, which we refer to as a key, defines how a character 47 * is collated in the given collation object. 48 * 49 * <p> 50 * For example, consider the following in Spanish: 51 * <blockquote> 52 * <pre> 53 * "ca" → the first key is key('c') and second key is key('a'). 54 * "cha" → the first key is key('ch') and second key is key('a'). 55 * </pre> 56 * </blockquote> 57 * And in German, 58 * <blockquote> 59 * <pre> 60 * "\u00e4b" → the first key is key('a'), the second key is key('e'), and 61 * the third key is key('b'). 62 * </pre> 63 * </blockquote> 64 * The key of a character is an integer composed of primary order(short), 65 * secondary order(byte), and tertiary order(byte). Java strictly defines 66 * the size and signedness of its primitive data types. Therefore, the static 67 * functions <code>primaryOrder</code>, <code>secondaryOrder</code>, and 68 * <code>tertiaryOrder</code> return <code>int</code>, <code>short</code>, 69 * and <code>short</code> respectively to ensure the correctness of the key 70 * value. 71 * 72 * <p> 73 * Example of the iterator usage, 74 * <blockquote> 75 * <pre> 76 * 77 * String testString = "This is a test"; 78 * Collator col = Collator.getInstance(); 79 * if (col instanceof RuleBasedCollator) { 80 * RuleBasedCollator ruleBasedCollator = (RuleBasedCollator)col; 81 * CollationElementIterator collationElementIterator = ruleBasedCollator.getCollationElementIterator(testString); 82 * int primaryOrder = CollationElementIterator.primaryOrder(collationElementIterator.next()); 83 * : 84 * } 85 * </pre> 86 * </blockquote> 87 * 88 * <p> 89 * <code>CollationElementIterator.next</code> returns the collation order 90 * of the next character. A collation order consists of primary order, 91 * secondary order and tertiary order. The data type of the collation 92 * order is <strong>int</strong>. The first 16 bits of a collation order 93 * is its primary order; the next 8 bits is the secondary order and the 94 * last 8 bits is the tertiary order. 95 * 96 * <p><b>Note:</b> <code>CollationElementIterator</code> is a part of 97 * <code>RuleBasedCollator</code> implementation. It is only usable 98 * with <code>RuleBasedCollator</code> instances. 99 * 100 * @see Collator 101 * @see RuleBasedCollator 102 * @author Helena Shih, Laura Werner, Richard Gillam 103 */ 104 public final class CollationElementIterator 105 { 106 /** 107 * Null order which indicates the end of string is reached by the 108 * cursor. 109 */ 110 public final static int NULLORDER = 0xffffffff; 111 112 // Android-removed: internal constructors. 113 114 // Android-added: ICU iterator to delegate to. 115 private android.icu.text.CollationElementIterator icuIterator; 116 117 // Android-added: internal constructor taking an ICU CollationElementIterator. CollationElementIterator(android.icu.text.CollationElementIterator iterator)118 CollationElementIterator(android.icu.text.CollationElementIterator iterator) { 119 icuIterator = iterator; 120 } 121 122 /** 123 * Resets the cursor to the beginning of the string. The next call 124 * to next() will return the first collation element in the string. 125 */ reset()126 public void reset() 127 { 128 // Android-changed: delegate to ICU CollationElementIterator. 129 icuIterator.reset(); 130 } 131 132 /** 133 * Get the next collation element in the string. <p>This iterator iterates 134 * over a sequence of collation elements that were built from the string. 135 * Because there isn't necessarily a one-to-one mapping from characters to 136 * collation elements, this doesn't mean the same thing as "return the 137 * collation element [or ordering priority] of the next character in the 138 * string".</p> 139 * <p>This function returns the collation element that the iterator is currently 140 * pointing to and then updates the internal pointer to point to the next element. 141 * previous() updates the pointer first and then returns the element. This 142 * means that when you change direction while iterating (i.e., call next() and 143 * then call previous(), or call previous() and then call next()), you'll get 144 * back the same element twice.</p> 145 * 146 * @return the next collation element 147 */ next()148 public int next() 149 { 150 // Android-changed: delegate to ICU CollationElementIterator. 151 return icuIterator.next(); 152 } 153 154 /** 155 * Get the previous collation element in the string. <p>This iterator iterates 156 * over a sequence of collation elements that were built from the string. 157 * Because there isn't necessarily a one-to-one mapping from characters to 158 * collation elements, this doesn't mean the same thing as "return the 159 * collation element [or ordering priority] of the previous character in the 160 * string".</p> 161 * <p>This function updates the iterator's internal pointer to point to the 162 * collation element preceding the one it's currently pointing to and then 163 * returns that element, while next() returns the current element and then 164 * updates the pointer. This means that when you change direction while 165 * iterating (i.e., call next() and then call previous(), or call previous() 166 * and then call next()), you'll get back the same element twice.</p> 167 * 168 * @return the previous collation element 169 * @since 1.2 170 */ previous()171 public int previous() 172 { 173 // Android-changed: delegate to ICU CollationElementIterator. 174 return icuIterator.previous(); 175 } 176 177 /** 178 * Return the primary component of a collation element. 179 * @param order the collation element 180 * @return the element's primary component 181 */ primaryOrder(int order)182 public final static int primaryOrder(int order) 183 { 184 // Android-changed: delegate to ICU CollationElementIterator. 185 return android.icu.text.CollationElementIterator.primaryOrder(order); 186 } 187 /** 188 * Return the secondary component of a collation element. 189 * @param order the collation element 190 * @return the element's secondary component 191 */ secondaryOrder(int order)192 public final static short secondaryOrder(int order) 193 { 194 // Android-changed: delegate to ICU CollationElementIterator. 195 return (short) android.icu.text.CollationElementIterator.secondaryOrder(order); 196 } 197 /** 198 * Return the tertiary component of a collation element. 199 * @param order the collation element 200 * @return the element's tertiary component 201 */ tertiaryOrder(int order)202 public final static short tertiaryOrder(int order) 203 { 204 // Android-changed: delegate to ICU CollationElementIterator. 205 return (short) android.icu.text.CollationElementIterator.tertiaryOrder(order); 206 } 207 208 /** 209 * Sets the iterator to point to the collation element corresponding to 210 * the specified character (the parameter is a CHARACTER offset in the 211 * original string, not an offset into its corresponding sequence of 212 * collation elements). The value returned by the next call to next() 213 * will be the collation element corresponding to the specified position 214 * in the text. If that position is in the middle of a contracting 215 * character sequence, the result of the next call to next() is the 216 * collation element for that sequence. This means that getOffset() 217 * is not guaranteed to return the same value as was passed to a preceding 218 * call to setOffset(). 219 * 220 * @param newOffset The new character offset into the original text. 221 * @since 1.2 222 */ 223 @SuppressWarnings("deprecation") // getBeginIndex, getEndIndex and setIndex are deprecated setOffset(int newOffset)224 public void setOffset(int newOffset) 225 { 226 // Android-changed: delegate to ICU CollationElementIterator. 227 icuIterator.setOffset(newOffset); 228 } 229 230 /** 231 * Returns the character offset in the original text corresponding to the next 232 * collation element. (That is, getOffset() returns the position in the text 233 * corresponding to the collation element that will be returned by the next 234 * call to next().) This value will always be the index of the FIRST character 235 * corresponding to the collation element (a contracting character sequence is 236 * when two or more characters all correspond to the same collation element). 237 * This means if you do setOffset(x) followed immediately by getOffset(), getOffset() 238 * won't necessarily return x. 239 * 240 * @return The character offset in the original text corresponding to the collation 241 * element that will be returned by the next call to next(). 242 * @since 1.2 243 */ getOffset()244 public int getOffset() 245 { 246 // Android-changed: delegate to ICU CollationElementIterator. 247 return icuIterator.getOffset(); 248 } 249 250 251 /** 252 * Return the maximum length of any expansion sequences that end 253 * with the specified comparison order. 254 * @param order a collation order returned by previous or next. 255 * @return the maximum length of any expansion sequences ending 256 * with the specified order. 257 * @since 1.2 258 */ getMaxExpansion(int order)259 public int getMaxExpansion(int order) 260 { 261 // Android-changed: delegate to ICU CollationElementIterator. 262 return icuIterator.getMaxExpansion(order); 263 } 264 265 /** 266 * Set a new string over which to iterate. 267 * 268 * @param source the new source text 269 * @since 1.2 270 */ setText(String source)271 public void setText(String source) 272 { 273 // Android-changed: delegate to ICU CollationElementIterator. 274 icuIterator.setText(source); 275 } 276 277 /** 278 * Set a new string over which to iterate. 279 * 280 * @param source the new source text. 281 * @since 1.2 282 */ setText(CharacterIterator source)283 public void setText(CharacterIterator source) 284 { 285 // Android-changed: delegate to ICU CollationElementIterator. 286 icuIterator.setText(source); 287 } 288 289 // Android-removed: private helper methods and fields. 290 } 291