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