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 UBool operator==(const ForwardCharacterIterator& that) const; 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; 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); 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; 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 196