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