icuSources/common/unicode/schriter.h

   1 /*
   2 ******************************************************************************
   3 *
   4 *   Copyright (C) 1998-2005, International Business Machines
   5 *   Corporation and others.  All Rights Reserved.
   6 *
   7 ******************************************************************************
   8 *
   9 * File schriter.h
  10 *
  11 * Modification History:
  12 *
  13 *   Date        Name        Description
  14 *  05/05/99     stephen     Cleaned up.
  15 ******************************************************************************
  16 */
  17
  18 #ifndef SCHRITER_H
  19 #define SCHRITER_H
  20
  21 #include "unicode/utypes.h"
  22 #include "unicode/chariter.h"
  23 #include "unicode/uchriter.h"
  24
  25 /**
  26  * \file
  27  * \brief C++ API: String Character Iterator
  28  */
  29
  30 U_NAMESPACE_BEGIN
  31 /**
  32  * A concrete subclass of CharacterIterator that iterates over the
  33  * characters (code units or code points) in a UnicodeString.
  34  * It's possible not only to create an
  35  * iterator that iterates over an entire UnicodeString, but also to
  36  * create one that iterates over only a subrange of a UnicodeString
  37  * (iterators over different subranges of the same UnicodeString don't
  38  * compare equal).
  39  * @see CharacterIterator
  40  * @see ForwardCharacterIterator
  41  * @stable ICU 2.0
  42  */
  43 class U_COMMON_API StringCharacterIterator : public UCharCharacterIterator {
  44 public:
  45   /**
  46    * Create an iterator over the UnicodeString referred to by "textStr".
  47    * The UnicodeString object is copied.
  48    * The iteration range is the whole string, and the starting position is 0.
  49    * @param textStr The unicode string used to create an iterator
  50    * @stable ICU 2.0
  51    */
  52   StringCharacterIterator(const UnicodeString& textStr);
  53
  54   /**
  55    * Create an iterator over the UnicodeString referred to by "textStr".
  56    * The iteration range is the whole string, and the starting
  57    * position is specified by "textPos".  If "textPos" is outside the valid
  58    * iteration range, the behavior of this object is undefined.
  59    * @param textStr The unicode string used to create an iterator
  60    * @param textPos The starting position of the iteration
  61    * @stable ICU 2.0
  62    */
  63   StringCharacterIterator(const UnicodeString&    textStr,
  64               int32_t              textPos);
  65
  66   /**
  67    * Create an iterator over the UnicodeString referred to by "textStr".
  68    * The UnicodeString object is copied.
  69    * The iteration range begins with the code unit specified by
  70    * "textBegin" and ends with the code unit BEFORE the code unit specfied
  71    * by "textEnd".  The starting position is specified by "textPos".  If
  72    * "textBegin" and "textEnd" don't form a valid range on "text" (i.e.,
  73    * textBegin >= textEnd or either is negative or greater than text.size()),
  74    * or "textPos" is outside the range defined by "textBegin" and "textEnd",
  75    * the behavior of this iterator is undefined.
  76    * @param textStr    The unicode string used to create the StringCharacterIterator
  77    * @param textBegin  The begin position of the iteration range
  78    * @param textEnd    The end position of the iteration range
  79    * @param textPos    The starting position of the iteration
  80    * @stable ICU 2.0
  81    */
  82   StringCharacterIterator(const UnicodeString&    textStr,
  83               int32_t              textBegin,
  84               int32_t              textEnd,
  85               int32_t              textPos);
  86
  87   /**
  88    * Copy constructor.  The new iterator iterates over the same range
  89    * of the same string as "that", and its initial position is the
  90    * same as "that"'s current position.
  91    * The UnicodeString object in "that" is copied.
  92    * @param that The StringCharacterIterator to be copied
  93    * @stable ICU 2.0
  94    */
  95   StringCharacterIterator(const StringCharacterIterator&  that);
  96
  97   /**
  98    * Destructor.
  99    * @stable ICU 2.0
 100    */
 101   virtual ~StringCharacterIterator();
 102
 103   /**
 104    * Assignment operator.  *this is altered to iterate over the same
 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   StringCharacterIterator&
 112   operator=(const StringCharacterIterator&    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 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    * Returns a new StringCharacterIterator referring to the same
 126    * character in the same range of the same string as this one.  The
 127    * caller must delete the new iterator.
 128    * @return the newly cloned object.
 129    * @stable ICU 2.0
 130    */
 131   virtual CharacterIterator* clone(void) const;
 132
 133   /**
 134    * Sets the iterator to iterate over the provided string.
 135    * @param newText The string to be iterated over
 136    * @stable ICU 2.0
 137    */
 138   void setText(const UnicodeString& newText);
 139
 140   /**
 141    * Copies the UnicodeString under iteration into the UnicodeString
 142    * referred to by "result".  Even if this iterator iterates across
 143    * only a part of this string, the whole string is copied.
 144    * @param result Receives a copy of the text under iteration.
 145    * @stable ICU 2.0
 146    */
 147   virtual void            getText(UnicodeString& result);
 148
 149   /**
 150    * Return a class ID for this object (not really public)
 151    * @return a class ID for this object.
 152    * @stable ICU 2.0
 153    */
 154   virtual UClassID         getDynamicClassID(void) const;
 155
 156   /**
 157    * Return a class ID for this class (not really public)
 158    * @return a class ID for this class
 159    * @stable ICU 2.0
 160    */
 161   static UClassID   U_EXPORT2 getStaticClassID(void);
 162
 163 protected:
 164   /**
 165    * Default constructor, iteration over empty string.
 166    * @stable ICU 2.0
 167    */
 168   StringCharacterIterator();
 169
 170   /**
 171    * Sets the iterator to iterate over the provided string.
 172    * @param newText The string to be iterated over
 173    * @param newTextLength The length of the String
 174    * @stable ICU 2.0
 175    */
 176   void setText(const UChar* newText, int32_t newTextLength);
 177
 178   /**
 179    * Copy of the iterated string object.
 180    * @stable ICU 2.0
 181    */
 182   UnicodeString            text;
 183
 184 };
 185
 186 U_NAMESPACE_END
 187 #endif