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