1/** 2******************************************************************************* 3* Copyright (C) 1996-2005, International Business Machines Corporation and * 4* others. All Rights Reserved. * 5******************************************************************************* 6* 7******************************************************************************* 8*/ 9 10package com.ibm.icu4jni.text; 11 12import java.text.CharacterIterator; 13 14 15/** 16* Collation element iterator JNI wrapper. 17* Iterates over the collation elements of a data string. 18* The iterator supports both forward and backwards full iteration, ie if 19* backwards iteration is performed in the midst of a forward iteration, the 20* result is undefined. 21* To perform a backwards iteration in the midst of a forward iteration, 22* reset() has to be called. 23* This will shift the position to either the start or the last character in the 24* data string depending on whether next() is called or previous(). 25* <pre> 26* RuleBasedCollator coll = Collator.getInstance(); 27* CollationElementIterator iterator = coll.getCollationElementIterator("abc"); 28* int ce = 0; 29* while (ce != CollationElementIterator.NULLORDER) { 30* ce = iterator.next(); 31* } 32* iterator.reset(); 33* while (ce != CollationElementIterator.NULLORDER) { 34* ce = iterator.previous(); 35* } 36* </pre> 37* @author syn wee quek 38* @stable ICU 2.4 39*/ 40 41public final class CollationElementIterator 42{ 43 // public data member ------------------------------------------- 44 45 /** 46 * @stable ICU 2.4 47 */ 48 public static final int NULLORDER = 0xFFFFFFFF; 49 50 // public methods ----------------------------------------------- 51 52 /** 53 * Reset the collation elements to their initial state. 54 * This will move the 'cursor' to the beginning of the text. 55 * @stable ICU 2.4 56 */ 57 public void reset() 58 { 59 NativeCollation.reset(m_collelemiterator_); 60 } 61 62 /** 63 * Get the ordering priority of the next collation element in the text. 64 * A single character may contain more than one collation element. 65 * @return next collation elements ordering, or NULLORDER if the end of the 66 * text is reached. 67 * @stable ICU 2.4 68 */ 69 public int next() 70 { 71 return NativeCollation.next(m_collelemiterator_); 72 } 73 74 /** 75 * Get the ordering priority of the previous collation element in the text. 76 * A single character may contain more than one collation element. 77 * @return previous collation element ordering, or NULLORDER if the end of 78 * the text is reached. 79 * @stable ICU 2.4 80 */ 81 public int previous() 82 { 83 return NativeCollation.previous(m_collelemiterator_); 84 } 85 86 /** 87 * Get the maximum length of any expansion sequences that end with the 88 * specified comparison order. 89 * @param order collation order returned by previous or next. 90 * @return maximum size of the expansion sequences ending with the collation 91 * element or 1 if collation element does not occur at the end of 92 * any expansion sequence 93 * @stable ICU 2.4 94 */ 95 public int getMaxExpansion(int order) 96 { 97 return NativeCollation.getMaxExpansion(m_collelemiterator_, order); 98 } 99 100 /** 101 * Set the text containing the collation elements. 102 * @param source text containing the collation elements. 103 * @stable ICU 2.4 104 */ 105 public void setText(String source) 106 { 107 NativeCollation.setText(m_collelemiterator_, source); 108 } 109 110 // BEGIN android-added 111 public void setText(CharacterIterator source) 112 { 113 NativeCollation.setText(m_collelemiterator_, source.toString()); 114 } 115 // END android-added 116 117 /** 118 * Get the offset of the current source character. 119 * This is an offset into the text of the character containing the current 120 * collation elements. 121 * @return offset of the current source character. 122 * @stable ICU 2.4 123 */ 124 public int getOffset() 125 { 126 return NativeCollation.getOffset(m_collelemiterator_); 127 } 128 129 /** 130 * Set the offset of the current source character. 131 * This is an offset into the text of the character to be processed. 132 * @param offset The desired character offset. 133 * @stable ICU 2.4 134 */ 135 public void setOffset(int offset) 136 { 137 NativeCollation.setOffset(m_collelemiterator_, offset); 138 } 139 140 /** 141 * Gets the primary order of a collation order. 142 * @param order the collation order 143 * @return the primary order of a collation order. 144 * @stable ICU 2.4 145 */ 146 public static int primaryOrder(int order) 147 { 148 return ((order & PRIMARY_ORDER_MASK_) >> PRIMARY_ORDER_SHIFT_) & 149 UNSIGNED_16_BIT_MASK_; 150 } 151 152 /** 153 * Gets the secondary order of a collation order. 154 * @param order the collation order 155 * @return the secondary order of a collation order. 156 * @stable ICU 2.4 157 */ 158 public static int secondaryOrder(int order) 159 { 160 return (order & SECONDARY_ORDER_MASK_) >> SECONDARY_ORDER_SHIFT_; 161 } 162 163 /** 164 * Gets the tertiary order of a collation order. 165 * @param order the collation order 166 * @return the tertiary order of a collation order. 167 * @stable ICU 2.4 168 */ 169 public static int tertiaryOrder(int order) 170 { 171 return order & TERTIARY_ORDER_MASK_; 172 } 173 174 // protected constructor ---------------------------------------- 175 176 /** 177 * CollationElementIteratorJNI constructor. 178 * The only caller of this class should be 179 * RuleBasedCollator.getCollationElementIterator(). 180 * @param collelemiteratoraddress address of C collationelementiterator 181 */ 182 CollationElementIterator(int collelemiteratoraddress) 183 { 184 m_collelemiterator_ = collelemiteratoraddress; 185 } 186 187 // protected methods -------------------------------------------- 188 189 /** 190 * Garbage collection. 191 * Close C collator and reclaim memory. 192 * @stable ICU 2.4 193 */ 194 protected void finalize() 195 { 196 NativeCollation.closeElements(m_collelemiterator_); 197 } 198 199 // private data members ----------------------------------------- 200 201 /** 202 * C collator 203 */ 204 private int m_collelemiterator_; 205 206 /** 207 * ICU constant primary order mask for collation elements 208 */ 209 private static final int PRIMARY_ORDER_MASK_ = 0xffff0000; 210 /** 211 * ICU constant secondary order mask for collation elements 212 */ 213 private static final int SECONDARY_ORDER_MASK_ = 0x0000ff00; 214 /** 215 * ICU constant tertiary order mask for collation elements 216 */ 217 private static final int TERTIARY_ORDER_MASK_ = 0x000000ff; 218 /** 219 * ICU constant primary order shift for collation elements 220 */ 221 private static final int PRIMARY_ORDER_SHIFT_ = 16; 222 /** 223 * ICU constant secondary order shift for collation elements 224 */ 225 private static final int SECONDARY_ORDER_SHIFT_ = 8; 226 /** 227 * Unsigned 16 bit mask 228 */ 229 private static final int UNSIGNED_16_BIT_MASK_ = 0x0000FFFF; 230} 231