1 /* 2 ********************************************************************** 3 * Copyright (C) 1998-2005, International Business Machines 4 * Corporation and others. All Rights Reserved. 5 ********************************************************************** 6 */ 7 8 #ifndef UCHRITER_H 9 #define UCHRITER_H 10 11 #include "unicode/utypes.h" 12 #include "unicode/chariter.h" 13 14 /** 15 * \file 16 * \brief C++ API: UChar Character Iterator 17 */ 18 19 U_NAMESPACE_BEGIN 20 21 /** 22 * A concrete subclass of CharacterIterator that iterates over the 23 * characters (code units or code points) in a UChar array. 24 * It's possible not only to create an 25 * iterator that iterates over an entire UChar array, but also to 26 * create one that iterates over only a subrange of a UChar array 27 * (iterators over different subranges of the same UChar array don't 28 * compare equal). 29 * @see CharacterIterator 30 * @see ForwardCharacterIterator 31 * @stable ICU 2.0 32 */ 33 class U_COMMON_API UCharCharacterIterator : public CharacterIterator { 34 public: 35 /** 36 * Create an iterator over the UChar array referred to by "textPtr". 37 * The iteration range is 0 to <code>length-1</code>. 38 * text is only aliased, not adopted (the 39 * destructor will not delete it). 40 * @param textPtr The UChar array to be iterated over 41 * @param length The length of the UChar array 42 * @stable ICU 2.0 43 */ 44 UCharCharacterIterator(const UChar* textPtr, int32_t length); 45 46 /** 47 * Create an iterator over the UChar array referred to by "textPtr". 48 * The iteration range is 0 to <code>length-1</code>. 49 * text is only aliased, not adopted (the 50 * destructor will not delete it). 51 * The starting 52 * position is specified by "position". If "position" is outside the valid 53 * iteration range, the behavior of this object is undefined. 54 * @param textPtr The UChar array to be iteratd over 55 * @param length The length of the UChar array 56 * @param position The starting position of the iteration 57 * @stable ICU 2.0 58 */ 59 UCharCharacterIterator(const UChar* textPtr, int32_t length, 60 int32_t position); 61 62 /** 63 * Create an iterator over the UChar array referred to by "textPtr". 64 * The iteration range is 0 to <code>end-1</code>. 65 * text is only aliased, not adopted (the 66 * destructor will not delete it). 67 * The starting 68 * position is specified by "position". If begin and end do not 69 * form a valid iteration range or "position" is outside the valid 70 * iteration range, the behavior of this object is undefined. 71 * @param textPtr The UChar array to be iterated over 72 * @param length The length of the UChar array 73 * @param textBegin The begin position of the iteration range 74 * @param textEnd The end position of the iteration range 75 * @param position The starting position of the iteration 76 * @stable ICU 2.0 77 */ 78 UCharCharacterIterator(const UChar* textPtr, int32_t length, 79 int32_t textBegin, 80 int32_t textEnd, 81 int32_t position); 82 83 /** 84 * Copy constructor. The new iterator iterates over the same range 85 * of the same string as "that", and its initial position is the 86 * same as "that"'s current position. 87 * @param that The UCharCharacterIterator to be copied 88 * @stable ICU 2.0 89 */ 90 UCharCharacterIterator(const UCharCharacterIterator& that); 91 92 /** 93 * Destructor. 94 * @stable ICU 2.0 95 */ 96 virtual ~UCharCharacterIterator(); 97 98 /** 99 * Assignment operator. *this is altered to iterate over the sane 100 * range of the same string as "that", and refers to the same 101 * character within that string as "that" does. 102 * @param that The object to be copied 103 * @return the newly created object 104 * @stable ICU 2.0 105 */ 106 UCharCharacterIterator& 107 operator=(const UCharCharacterIterator& that); 108 109 /** 110 * Returns true if the iterators iterate over the same range of the 111 * same string and are pointing at the same character. 112 * @param that The ForwardCharacterIterator used to be compared for equality 113 * @return true if the iterators iterate over the same range of the 114 * same string and are pointing at the same character. 115 * @stable ICU 2.0 116 */ 117 virtual UBool operator==(const ForwardCharacterIterator& that) const; 118 119 /** 120 * Generates a hash code for this iterator. 121 * @return the hash code. 122 * @stable ICU 2.0 123 */ 124 virtual int32_t hashCode(void) const; 125 126 /** 127 * Returns a new UCharCharacterIterator referring to the same 128 * character in the same range of the same string as this one. The 129 * caller must delete the new iterator. 130 * @return the CharacterIterator newly created 131 * @stable ICU 2.0 132 */ 133 virtual CharacterIterator* clone(void) const; 134 135 /** 136 * Sets the iterator to refer to the first code unit in its 137 * iteration range, and returns that code unit. 138 * This can be used to begin an iteration with next(). 139 * @return the first code unit in its iteration range. 140 * @stable ICU 2.0 141 */ 142 virtual UChar first(void); 143 144 /** 145 * Sets the iterator to refer to the first code unit in its 146 * iteration range, returns that code unit, and moves the position 147 * to the second code unit. This is an alternative to setToStart() 148 * for forward iteration with nextPostInc(). 149 * @return the first code unit in its iteration range 150 * @stable ICU 2.0 151 */ 152 virtual UChar firstPostInc(void); 153 154 /** 155 * Sets the iterator to refer to the first code point in its 156 * iteration range, and returns that code unit, 157 * This can be used to begin an iteration with next32(). 158 * Note that an iteration with next32PostInc(), beginning with, 159 * e.g., setToStart() or firstPostInc(), is more efficient. 160 * @return the first code point in its iteration range 161 * @stable ICU 2.0 162 */ 163 virtual UChar32 first32(void); 164 165 /** 166 * Sets the iterator to refer to the first code point in its 167 * iteration range, returns that code point, and moves the position 168 * to the second code point. This is an alternative to setToStart() 169 * for forward iteration with next32PostInc(). 170 * @return the first code point in its iteration range. 171 * @stable ICU 2.0 172 */ 173 virtual UChar32 first32PostInc(void); 174 175 /** 176 * Sets the iterator to refer to the last code unit in its 177 * iteration range, and returns that code unit. 178 * This can be used to begin an iteration with previous(). 179 * @return the last code unit in its iteration range. 180 * @stable ICU 2.0 181 */ 182 virtual UChar last(void); 183 184 /** 185 * Sets the iterator to refer to the last code point in its 186 * iteration range, and returns that code unit. 187 * This can be used to begin an iteration with previous32(). 188 * @return the last code point in its iteration range. 189 * @stable ICU 2.0 190 */ 191 virtual UChar32 last32(void); 192 193 /** 194 * Sets the iterator to refer to the "position"-th code unit 195 * in the text-storage object the iterator refers to, and 196 * returns that code unit. 197 * @param position the position within the text-storage object 198 * @return the code unit 199 * @stable ICU 2.0 200 */ 201 virtual UChar setIndex(int32_t position); 202 203 /** 204 * Sets the iterator to refer to the beginning of the code point 205 * that contains the "position"-th code unit 206 * in the text-storage object the iterator refers to, and 207 * returns that code point. 208 * The current position is adjusted to the beginning of the code point 209 * (its first code unit). 210 * @param position the position within the text-storage object 211 * @return the code unit 212 * @stable ICU 2.0 213 */ 214 virtual UChar32 setIndex32(int32_t position); 215 216 /** 217 * Returns the code unit the iterator currently refers to. 218 * @return the code unit the iterator currently refers to. 219 * @stable ICU 2.0 220 */ 221 virtual UChar current(void) const; 222 223 /** 224 * Returns the code point the iterator currently refers to. 225 * @return the code point the iterator currently refers to. 226 * @stable ICU 2.0 227 */ 228 virtual UChar32 current32(void) const; 229 230 /** 231 * Advances to the next code unit in the iteration range (toward 232 * endIndex()), and returns that code unit. If there are no more 233 * code units to return, returns DONE. 234 * @return the next code unit in the iteration range. 235 * @stable ICU 2.0 236 */ 237 virtual UChar next(void); 238 239 /** 240 * Gets the current code unit for returning and advances to the next code unit 241 * in the iteration range 242 * (toward endIndex()). If there are 243 * no more code units to return, returns DONE. 244 * @return the current code unit. 245 * @stable ICU 2.0 246 */ 247 virtual UChar nextPostInc(void); 248 249 /** 250 * Advances to the next code point in the iteration range (toward 251 * endIndex()), and returns that code point. If there are no more 252 * code points to return, returns DONE. 253 * Note that iteration with "pre-increment" semantics is less 254 * efficient than iteration with "post-increment" semantics 255 * that is provided by next32PostInc(). 256 * @return the next code point in the iteration range. 257 * @stable ICU 2.0 258 */ 259 virtual UChar32 next32(void); 260 261 /** 262 * Gets the current code point for returning and advances to the next code point 263 * in the iteration range 264 * (toward endIndex()). If there are 265 * no more code points to return, returns DONE. 266 * @return the current point. 267 * @stable ICU 2.0 268 */ 269 virtual UChar32 next32PostInc(void); 270 271 /** 272 * Returns FALSE if there are no more code units or code points 273 * at or after the current position in the iteration range. 274 * This is used with nextPostInc() or next32PostInc() in forward 275 * iteration. 276 * @return FALSE if there are no more code units or code points 277 * at or after the current position in the iteration range. 278 * @stable ICU 2.0 279 */ 280 virtual UBool hasNext(); 281 282 /** 283 * Advances to the previous code unit in the iteration range (toward 284 * startIndex()), and returns that code unit. If there are no more 285 * code units to return, returns DONE. 286 * @return the previous code unit in the iteration range. 287 * @stable ICU 2.0 288 */ 289 virtual UChar previous(void); 290 291 /** 292 * Advances to the previous code point in the iteration range (toward 293 * startIndex()), and returns that code point. If there are no more 294 * code points to return, returns DONE. 295 * @return the previous code point in the iteration range. 296 * @stable ICU 2.0 297 */ 298 virtual UChar32 previous32(void); 299 300 /** 301 * Returns FALSE if there are no more code units or code points 302 * before the current position in the iteration range. 303 * This is used with previous() or previous32() in backward 304 * iteration. 305 * @return FALSE if there are no more code units or code points 306 * before the current position in the iteration range. 307 * @stable ICU 2.0 308 */ 309 virtual UBool hasPrevious(); 310 311 /** 312 * Moves the current position relative to the start or end of the 313 * iteration range, or relative to the current position itself. 314 * The movement is expressed in numbers of code units forward 315 * or backward by specifying a positive or negative delta. 316 * @param delta the position relative to origin. A positive delta means forward; 317 * a negative delta means backward. 318 * @param origin Origin enumeration {kStart, kCurrent, kEnd} 319 * @return the new position 320 * @stable ICU 2.0 321 */ 322 virtual int32_t move(int32_t delta, EOrigin origin); 323 324 /** 325 * Moves the current position relative to the start or end of the 326 * iteration range, or relative to the current position itself. 327 * The movement is expressed in numbers of code points forward 328 * or backward by specifying a positive or negative delta. 329 * @param delta the position relative to origin. A positive delta means forward; 330 * a negative delta means backward. 331 * @param origin Origin enumeration {kStart, kCurrent, kEnd} 332 * @return the new position 333 * @stable ICU 2.0 334 */ 335 virtual int32_t move32(int32_t delta, EOrigin origin); 336 337 /** 338 * Sets the iterator to iterate over a new range of text 339 * @stable ICU 2.0 340 */ 341 void setText(const UChar* newText, int32_t newTextLength); 342 343 /** 344 * Copies the UChar array under iteration into the UnicodeString 345 * referred to by "result". Even if this iterator iterates across 346 * only a part of this string, the whole string is copied. 347 * @param result Receives a copy of the text under iteration. 348 * @stable ICU 2.0 349 */ 350 virtual void getText(UnicodeString& result); 351 352 /** 353 * Return a class ID for this class (not really public) 354 * @return a class ID for this class 355 * @stable ICU 2.0 356 */ 357 static UClassID U_EXPORT2 getStaticClassID(void); 358 359 /** 360 * Return a class ID for this object (not really public) 361 * @return a class ID for this object. 362 * @stable ICU 2.0 363 */ 364 virtual UClassID getDynamicClassID(void) const; 365 366 protected: 367 /** 368 * Protected constructor 369 * @stable ICU 2.0 370 */ 371 UCharCharacterIterator(); 372 /** 373 * Protected member text 374 * @stable ICU 2.0 375 */ 376 const UChar* text; 377 378 }; 379 380 U_NAMESPACE_END 381 #endif 382