1// © 2016 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
3/*
4**********************************************************************
5* Copyright (C) 1998-2005, International Business Machines
6* Corporation and others. All Rights Reserved.
7**********************************************************************
8*/
9
10#ifndef UCHRITER_H
11#define UCHRITER_H
12
13#include "unicode/utypes.h"
14
15#if U_SHOW_CPLUSPLUS_API
16
17#include "unicode/chariter.h"
18
19/**
20 * \file
21 * \brief C++ API: char16_t Character Iterator
22 */
23
24U_NAMESPACE_BEGIN
25
26/**
27 * A concrete subclass of CharacterIterator that iterates over the
28 * characters (code units or code points) in a char16_t array.
29 * It's possible not only to create an
30 * iterator that iterates over an entire char16_t array, but also to
31 * create one that iterates over only a subrange of a char16_t array
32 * (iterators over different subranges of the same char16_t array don't
33 * compare equal).
34 * @see CharacterIterator
35 * @see ForwardCharacterIterator
36 * @stable ICU 2.0
37 */
38class U_COMMON_API UCharCharacterIterator : public CharacterIterator {
39public:
40 /**
41 * Create an iterator over the char16_t array referred to by "textPtr".
42 * The iteration range is 0 to <code>length-1</code>.
43 * text is only aliased, not adopted (the
44 * destructor will not delete it).
45 * @param textPtr The char16_t array to be iterated over
46 * @param length The length of the char16_t array
47 * @stable ICU 2.0
48 */
49 UCharCharacterIterator(ConstChar16Ptr textPtr, int32_t length);
50
51 /**
52 * Create an iterator over the char16_t array referred to by "textPtr".
53 * The iteration range is 0 to <code>length-1</code>.
54 * text is only aliased, not adopted (the
55 * destructor will not delete it).
56 * The starting
57 * position is specified by "position". If "position" is outside the valid
58 * iteration range, the behavior of this object is undefined.
59 * @param textPtr The char16_t array to be iteratd over
60 * @param length The length of the char16_t array
61 * @param position The starting position of the iteration
62 * @stable ICU 2.0
63 */
64 UCharCharacterIterator(ConstChar16Ptr textPtr, int32_t length,
65 int32_t position);
66
67 /**
68 * Create an iterator over the char16_t array referred to by "textPtr".
69 * The iteration range is 0 to <code>end-1</code>.
70 * text is only aliased, not adopted (the
71 * destructor will not delete it).
72 * The starting
73 * position is specified by "position". If begin and end do not
74 * form a valid iteration range or "position" is outside the valid
75 * iteration range, the behavior of this object is undefined.
76 * @param textPtr The char16_t array to be iterated over
77 * @param length The length of the char16_t array
78 * @param textBegin The begin position of the iteration range
79 * @param textEnd The end position of the iteration range
80 * @param position The starting position of the iteration
81 * @stable ICU 2.0
82 */
83 UCharCharacterIterator(ConstChar16Ptr textPtr, int32_t length,
84 int32_t textBegin,
85 int32_t textEnd,
86 int32_t position);
87
88 /**
89 * Copy constructor. The new iterator iterates over the same range
90 * of the same string as "that", and its initial position is the
91 * same as "that"'s current position.
92 * @param that The UCharCharacterIterator to be copied
93 * @stable ICU 2.0
94 */
95 UCharCharacterIterator(const UCharCharacterIterator& that);
96
97 /**
98 * Destructor.
99 * @stable ICU 2.0
100 */
101 virtual ~UCharCharacterIterator();
102
103 /**
104 * Assignment operator. *this is altered to iterate over the sane
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 UCharCharacterIterator&
112 operator=(const UCharCharacterIterator& 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 used 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 * Generates a hash code for this iterator.
126 * @return the hash code.
127 * @stable ICU 2.0
128 */
129 virtual int32_t hashCode(void) const;
130
131 /**
132 * Returns a new UCharCharacterIterator referring to the same
133 * character in the same range of the same string as this one. The
134 * caller must delete the new iterator.
135 * @return the CharacterIterator newly created
136 * @stable ICU 2.0
137 */
138 virtual UCharCharacterIterator* clone() const;
139
140 /**
141 * Sets the iterator to refer to the first code unit in its
142 * iteration range, and returns that code unit.
143 * This can be used to begin an iteration with next().
144 * @return the first code unit in its iteration range.
145 * @stable ICU 2.0
146 */
147 virtual char16_t first(void);
148
149 /**
150 * Sets the iterator to refer to the first code unit in its
151 * iteration range, returns that code unit, and moves the position
152 * to the second code unit. This is an alternative to setToStart()
153 * for forward iteration with nextPostInc().
154 * @return the first code unit in its iteration range
155 * @stable ICU 2.0
156 */
157 virtual char16_t firstPostInc(void);
158
159 /**
160 * Sets the iterator to refer to the first code point in its
161 * iteration range, and returns that code unit,
162 * This can be used to begin an iteration with next32().
163 * Note that an iteration with next32PostInc(), beginning with,
164 * e.g., setToStart() or firstPostInc(), is more efficient.
165 * @return the first code point in its iteration range
166 * @stable ICU 2.0
167 */
168 virtual UChar32 first32(void);
169
170 /**
171 * Sets the iterator to refer to the first code point in its
172 * iteration range, returns that code point, and moves the position
173 * to the second code point. This is an alternative to setToStart()
174 * for forward iteration with next32PostInc().
175 * @return the first code point in its iteration range.
176 * @stable ICU 2.0
177 */
178 virtual UChar32 first32PostInc(void);
179
180 /**
181 * Sets the iterator to refer to the last code unit in its
182 * iteration range, and returns that code unit.
183 * This can be used to begin an iteration with previous().
184 * @return the last code unit in its iteration range.
185 * @stable ICU 2.0
186 */
187 virtual char16_t last(void);
188
189 /**
190 * Sets the iterator to refer to the last code point in its
191 * iteration range, and returns that code unit.
192 * This can be used to begin an iteration with previous32().
193 * @return the last code point in its iteration range.
194 * @stable ICU 2.0
195 */
196 virtual UChar32 last32(void);
197
198 /**
199 * Sets the iterator to refer to the "position"-th code unit
200 * in the text-storage object the iterator refers to, and
201 * returns that code unit.
202 * @param position the position within the text-storage object
203 * @return the code unit
204 * @stable ICU 2.0
205 */
206 virtual char16_t setIndex(int32_t position);
207
208 /**
209 * Sets the iterator to refer to the beginning of the code point
210 * that contains the "position"-th code unit
211 * in the text-storage object the iterator refers to, and
212 * returns that code point.
213 * The current position is adjusted to the beginning of the code point
214 * (its first code unit).
215 * @param position the position within the text-storage object
216 * @return the code unit
217 * @stable ICU 2.0
218 */
219 virtual UChar32 setIndex32(int32_t position);
220
221 /**
222 * Returns the code unit the iterator currently refers to.
223 * @return the code unit the iterator currently refers to.
224 * @stable ICU 2.0
225 */
226 virtual char16_t current(void) const;
227
228 /**
229 * Returns the code point the iterator currently refers to.
230 * @return the code point the iterator currently refers to.
231 * @stable ICU 2.0
232 */
233 virtual UChar32 current32(void) const;
234
235 /**
236 * Advances to the next code unit in the iteration range (toward
237 * endIndex()), and returns that code unit. If there are no more
238 * code units to return, returns DONE.
239 * @return the next code unit in the iteration range.
240 * @stable ICU 2.0
241 */
242 virtual char16_t next(void);
243
244 /**
245 * Gets the current code unit for returning and advances to the next code unit
246 * in the iteration range
247 * (toward endIndex()). If there are
248 * no more code units to return, returns DONE.
249 * @return the current code unit.
250 * @stable ICU 2.0
251 */
252 virtual char16_t nextPostInc(void);
253
254 /**
255 * Advances to the next code point in the iteration range (toward
256 * endIndex()), and returns that code point. If there are no more
257 * code points to return, returns DONE.
258 * Note that iteration with "pre-increment" semantics is less
259 * efficient than iteration with "post-increment" semantics
260 * that is provided by next32PostInc().
261 * @return the next code point in the iteration range.
262 * @stable ICU 2.0
263 */
264 virtual UChar32 next32(void);
265
266 /**
267 * Gets the current code point for returning and advances to the next code point
268 * in the iteration range
269 * (toward endIndex()). If there are
270 * no more code points to return, returns DONE.
271 * @return the current point.
272 * @stable ICU 2.0
273 */
274 virtual UChar32 next32PostInc(void);
275
276 /**
277 * Returns FALSE if there are no more code units or code points
278 * at or after the current position in the iteration range.
279 * This is used with nextPostInc() or next32PostInc() in forward
280 * iteration.
281 * @return FALSE if there are no more code units or code points
282 * at or after the current position in the iteration range.
283 * @stable ICU 2.0
284 */
285 virtual UBool hasNext();
286
287 /**
288 * Advances to the previous code unit in the iteration range (toward
289 * startIndex()), and returns that code unit. If there are no more
290 * code units to return, returns DONE.
291 * @return the previous code unit in the iteration range.
292 * @stable ICU 2.0
293 */
294 virtual char16_t previous(void);
295
296 /**
297 * Advances to the previous code point in the iteration range (toward
298 * startIndex()), and returns that code point. If there are no more
299 * code points to return, returns DONE.
300 * @return the previous code point in the iteration range.
301 * @stable ICU 2.0
302 */
303 virtual UChar32 previous32(void);
304
305 /**
306 * Returns FALSE if there are no more code units or code points
307 * before the current position in the iteration range.
308 * This is used with previous() or previous32() in backward
309 * iteration.
310 * @return FALSE if there are no more code units or code points
311 * before the current position in the iteration range.
312 * @stable ICU 2.0
313 */
314 virtual UBool hasPrevious();
315
316 /**
317 * Moves the current position relative to the start or end of the
318 * iteration range, or relative to the current position itself.
319 * The movement is expressed in numbers of code units forward
320 * or backward by specifying a positive or negative delta.
321 * @param delta the position relative to origin. A positive delta means forward;
322 * a negative delta means backward.
323 * @param origin Origin enumeration {kStart, kCurrent, kEnd}
324 * @return the new position
325 * @stable ICU 2.0
326 */
327 virtual int32_t move(int32_t delta, EOrigin origin);
328
329 /**
330 * Moves the current position relative to the start or end of the
331 * iteration range, or relative to the current position itself.
332 * The movement is expressed in numbers of code points forward
333 * or backward by specifying a positive or negative delta.
334 * @param delta the position relative to origin. A positive delta means forward;
335 * a negative delta means backward.
336 * @param origin Origin enumeration {kStart, kCurrent, kEnd}
337 * @return the new position
338 * @stable ICU 2.0
339 */
340#ifdef move32
341 // One of the system headers right now is sometimes defining a conflicting macro we don't use
342#undef move32
343#endif
344 virtual int32_t move32(int32_t delta, EOrigin origin);
345
346 /**
347 * Sets the iterator to iterate over a new range of text
348 * @stable ICU 2.0
349 */
350 void setText(ConstChar16Ptr newText, int32_t newTextLength);
351
352 /**
353 * Copies the char16_t array under iteration into the UnicodeString
354 * referred to by "result". Even if this iterator iterates across
355 * only a part of this string, the whole string is copied.
356 * @param result Receives a copy of the text under iteration.
357 * @stable ICU 2.0
358 */
359 virtual void getText(UnicodeString& result);
360
361 /**
362 * Return a class ID for this class (not really public)
363 * @return a class ID for this class
364 * @stable ICU 2.0
365 */
366 static UClassID U_EXPORT2 getStaticClassID(void);
367
368 /**
369 * Return a class ID for this object (not really public)
370 * @return a class ID for this object.
371 * @stable ICU 2.0
372 */
373 virtual UClassID getDynamicClassID(void) const;
374
375protected:
376 /**
377 * Protected constructor
378 * @stable ICU 2.0
379 */
380 UCharCharacterIterator();
381 /**
382 * Protected member text
383 * @stable ICU 2.0
384 */
385 const char16_t* text;
386
387};
388
389U_NAMESPACE_END
390
391#endif /* U_SHOW_CPLUSPLUS_API */
392
393#endif
394