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