Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/uchriter.h @ 69:33d812a61356

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