icuSources/common/unicode/schriter.h

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