icuSources/common/unicode/uchriter.h

   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