2 **********************************************************************
3 * Copyright (C) 1998-2005, International Business Machines
4 * Corporation and others. All Rights Reserved.
5 **********************************************************************
11 #include "unicode/utypes.h"
12 #include "unicode/chariter.h"
16 * \brief C++ API: UChar Character Iterator
22 * A concrete subclass of CharacterIterator that iterates over the
23 * characters (code units or code points) in a UChar array.
24 * It's possible not only to create an
25 * iterator that iterates over an entire UChar array, but also to
26 * create one that iterates over only a subrange of a UChar array
27 * (iterators over different subranges of the same UChar array don't
29 * @see CharacterIterator
30 * @see ForwardCharacterIterator
33 class U_COMMON_API UCharCharacterIterator : public CharacterIterator {
36 * Create an iterator over the UChar array referred to by "textPtr".
37 * The iteration range is 0 to <code>length-1</code>.
38 * text is only aliased, not adopted (the
39 * destructor will not delete it).
40 * @param textPtr The UChar array to be iterated over
41 * @param length The length of the UChar array
44 UCharCharacterIterator(const UChar* textPtr, int32_t length);
47 * Create an iterator over the UChar array referred to by "textPtr".
48 * The iteration range is 0 to <code>length-1</code>.
49 * text is only aliased, not adopted (the
50 * destructor will not delete it).
52 * position is specified by "position". If "position" is outside the valid
53 * iteration range, the behavior of this object is undefined.
54 * @param textPtr The UChar array to be iteratd over
55 * @param length The length of the UChar array
56 * @param position The starting position of the iteration
59 UCharCharacterIterator(const UChar* textPtr, int32_t length,
63 * Create an iterator over the UChar array referred to by "textPtr".
64 * The iteration range is 0 to <code>end-1</code>.
65 * text is only aliased, not adopted (the
66 * destructor will not delete it).
68 * position is specified by "position". If begin and end do not
69 * form a valid iteration range or "position" is outside the valid
70 * iteration range, the behavior of this object is undefined.
71 * @param textPtr The UChar array to be iterated over
72 * @param length The length of the UChar array
73 * @param textBegin The begin position of the iteration range
74 * @param textEnd The end position of the iteration range
75 * @param position The starting position of the iteration
78 UCharCharacterIterator(const UChar* textPtr, int32_t length,
84 * Copy constructor. The new iterator iterates over the same range
85 * of the same string as "that", and its initial position is the
86 * same as "that"'s current position.
87 * @param that The UCharCharacterIterator to be copied
90 UCharCharacterIterator(const UCharCharacterIterator& that);
96 virtual ~UCharCharacterIterator();
99 * Assignment operator. *this is altered to iterate over the sane
100 * range of the same string as "that", and refers to the same
101 * character within that string as "that" does.
102 * @param that The object to be copied
103 * @return the newly created object
106 UCharCharacterIterator&
107 operator=(const UCharCharacterIterator& that);
110 * Returns true if the iterators iterate over the same range of the
111 * same string and are pointing at the same character.
112 * @param that The ForwardCharacterIterator used to be compared for equality
113 * @return true if the iterators iterate over the same range of the
114 * same string and are pointing at the same character.
117 virtual UBool operator==(const ForwardCharacterIterator& that) const;
120 * Generates a hash code for this iterator.
121 * @return the hash code.
124 virtual int32_t hashCode(void) const;
127 * Returns a new UCharCharacterIterator 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 CharacterIterator newly created
133 virtual CharacterIterator* clone(void) const;
136 * Sets the iterator to refer to the first code unit in its
137 * iteration range, and returns that code unit.
138 * This can be used to begin an iteration with next().
139 * @return the first code unit in its iteration range.
142 virtual UChar first(void);
145 * Sets the iterator to refer to the first code unit in its
146 * iteration range, returns that code unit, and moves the position
147 * to the second code unit. This is an alternative to setToStart()
148 * for forward iteration with nextPostInc().
149 * @return the first code unit in its iteration range
152 virtual UChar firstPostInc(void);
155 * Sets the iterator to refer to the first code point in its
156 * iteration range, and returns that code unit,
157 * This can be used to begin an iteration with next32().
158 * Note that an iteration with next32PostInc(), beginning with,
159 * e.g., setToStart() or firstPostInc(), is more efficient.
160 * @return the first code point in its iteration range
163 virtual UChar32 first32(void);
166 * Sets the iterator to refer to the first code point in its
167 * iteration range, returns that code point, and moves the position
168 * to the second code point. This is an alternative to setToStart()
169 * for forward iteration with next32PostInc().
170 * @return the first code point in its iteration range.
173 virtual UChar32 first32PostInc(void);
176 * Sets the iterator to refer to the last code unit in its
177 * iteration range, and returns that code unit.
178 * This can be used to begin an iteration with previous().
179 * @return the last code unit in its iteration range.
182 virtual UChar last(void);
185 * Sets the iterator to refer to the last code point in its
186 * iteration range, and returns that code unit.
187 * This can be used to begin an iteration with previous32().
188 * @return the last code point in its iteration range.
191 virtual UChar32 last32(void);
194 * Sets the iterator to refer to the "position"-th code unit
195 * in the text-storage object the iterator refers to, and
196 * returns that code unit.
197 * @param position the position within the text-storage object
198 * @return the code unit
201 virtual UChar setIndex(int32_t position);
204 * Sets the iterator to refer to the beginning of the code point
205 * that contains the "position"-th code unit
206 * in the text-storage object the iterator refers to, and
207 * returns that code point.
208 * The current position is adjusted to the beginning of the code point
209 * (its first code unit).
210 * @param position the position within the text-storage object
211 * @return the code unit
214 virtual UChar32 setIndex32(int32_t position);
217 * Returns the code unit the iterator currently refers to.
218 * @return the code unit the iterator currently refers to.
221 virtual UChar current(void) const;
224 * Returns the code point the iterator currently refers to.
225 * @return the code point the iterator currently refers to.
228 virtual UChar32 current32(void) const;
231 * Advances to the next code unit in the iteration range (toward
232 * endIndex()), and returns that code unit. If there are no more
233 * code units to return, returns DONE.
234 * @return the next code unit in the iteration range.
237 virtual UChar next(void);
240 * Gets the current code unit for returning and advances to the next code unit
241 * in the iteration range
242 * (toward endIndex()). If there are
243 * no more code units to return, returns DONE.
244 * @return the current code unit.
247 virtual UChar nextPostInc(void);
250 * Advances to the next code point in the iteration range (toward
251 * endIndex()), and returns that code point. If there are no more
252 * code points to return, returns DONE.
253 * Note that iteration with "pre-increment" semantics is less
254 * efficient than iteration with "post-increment" semantics
255 * that is provided by next32PostInc().
256 * @return the next code point in the iteration range.
259 virtual UChar32 next32(void);
262 * Gets the current code point for returning and advances to the next code point
263 * in the iteration range
264 * (toward endIndex()). If there are
265 * no more code points to return, returns DONE.
266 * @return the current point.
269 virtual UChar32 next32PostInc(void);
272 * Returns FALSE if there are no more code units or code points
273 * at or after the current position in the iteration range.
274 * This is used with nextPostInc() or next32PostInc() in forward
276 * @return FALSE if there are no more code units or code points
277 * at or after the current position in the iteration range.
280 virtual UBool hasNext();
283 * Advances to the previous code unit in the iteration range (toward
284 * startIndex()), and returns that code unit. If there are no more
285 * code units to return, returns DONE.
286 * @return the previous code unit in the iteration range.
289 virtual UChar previous(void);
292 * Advances to the previous code point in the iteration range (toward
293 * startIndex()), and returns that code point. If there are no more
294 * code points to return, returns DONE.
295 * @return the previous code point in the iteration range.
298 virtual UChar32 previous32(void);
301 * Returns FALSE if there are no more code units or code points
302 * before the current position in the iteration range.
303 * This is used with previous() or previous32() in backward
305 * @return FALSE if there are no more code units or code points
306 * before the current position in the iteration range.
309 virtual UBool hasPrevious();
312 * Moves the current position relative to the start or end of the
313 * iteration range, or relative to the current position itself.
314 * The movement is expressed in numbers of code units forward
315 * or backward by specifying a positive or negative delta.
316 * @param delta the position relative to origin. A positive delta means forward;
317 * a negative delta means backward.
318 * @param origin Origin enumeration {kStart, kCurrent, kEnd}
319 * @return the new position
322 virtual int32_t move(int32_t delta, EOrigin origin);
325 * Moves the current position relative to the start or end of the
326 * iteration range, or relative to the current position itself.
327 * The movement is expressed in numbers of code points forward
328 * or backward by specifying a positive or negative delta.
329 * @param delta the position relative to origin. A positive delta means forward;
330 * a negative delta means backward.
331 * @param origin Origin enumeration {kStart, kCurrent, kEnd}
332 * @return the new position
335 virtual int32_t move32(int32_t delta, EOrigin origin);
338 * Sets the iterator to iterate over a new range of text
341 void setText(const UChar* newText, int32_t newTextLength);
344 * Copies the UChar array under iteration into the UnicodeString
345 * referred to by "result". Even if this iterator iterates across
346 * only a part of this string, the whole string is copied.
347 * @param result Receives a copy of the text under iteration.
350 virtual void getText(UnicodeString& result);
353 * Return a class ID for this class (not really public)
354 * @return a class ID for this class
357 static UClassID U_EXPORT2 getStaticClassID(void);
360 * Return a class ID for this object (not really public)
361 * @return a class ID for this object.
364 virtual UClassID getDynamicClassID(void) const;
368 * Protected constructor
371 UCharCharacterIterator();
373 * Protected member text