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