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 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 char16_t* 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 190