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