include/unicode/schriter.h

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