2 ******************************************************************************
4 * Copyright (C) 1998-2005, International Business Machines
5 * Corporation and others. All Rights Reserved.
7 ******************************************************************************
11 * Modification History:
13 * Date Name Description
14 * 05/05/99 stephen Cleaned up.
15 ******************************************************************************
21 #include "unicode/utypes.h"
22 #include "unicode/chariter.h"
23 #include "unicode/uchriter.h"
27 * \brief C++ API: String Character Iterator
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
39 * @see CharacterIterator
40 * @see ForwardCharacterIterator
43 class U_COMMON_API StringCharacterIterator : public UCharCharacterIterator {
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
52 StringCharacterIterator(const UnicodeString& textStr);
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
63 StringCharacterIterator(const UnicodeString& textStr,
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
82 StringCharacterIterator(const UnicodeString& textStr,
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
95 StringCharacterIterator(const StringCharacterIterator& that);
101 virtual ~StringCharacterIterator();
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.
111 StringCharacterIterator&
112 operator=(const StringCharacterIterator& that);
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.
122 virtual UBool operator==(const ForwardCharacterIterator& that) const;
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.
131 virtual CharacterIterator* clone(void) const;
134 * Sets the iterator to iterate over the provided string.
135 * @param newText The string to be iterated over
138 void setText(const UnicodeString& newText);
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.
147 virtual void getText(UnicodeString& result);
150 * Return a class ID for this object (not really public)
151 * @return a class ID for this object.
154 virtual UClassID getDynamicClassID(void) const;
157 * Return a class ID for this class (not really public)
158 * @return a class ID for this class
161 static UClassID U_EXPORT2 getStaticClassID(void);
165 * Default constructor, iteration over empty string.
168 StringCharacterIterator();
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
176 void setText(const UChar* newText, int32_t newTextLength);
179 * Copy of the iterated string object.