icuSources/common/unicode/uchriter.h

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