source/common/unicode/schriter.h

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