OLD | NEW |
| (Empty) |
1 /* | |
2 ********************************************************************** | |
3 * Copyright (C) 1998-2005, International Business Machines | |
4 * Corporation and others. All Rights Reserved. | |
5 ********************************************************************** | |
6 */ | |
7 | |
8 #ifndef UCHRITER_H | |
9 #define UCHRITER_H | |
10 | |
11 #include "unicode/utypes.h" | |
12 #include "unicode/chariter.h" | |
13 | |
14 /** | |
15 * \file | |
16 * \brief C++ API: UChar Character Iterator | |
17 */ | |
18 | |
19 U_NAMESPACE_BEGIN | |
20 | |
21 /** | |
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 | |
28 * compare equal). | |
29 * @see CharacterIterator | |
30 * @see ForwardCharacterIterator | |
31 * @stable ICU 2.0 | |
32 */ | |
33 class U_COMMON_API UCharCharacterIterator : public CharacterIterator { | |
34 public: | |
35 /** | |
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 | |
42 * @stable ICU 2.0 | |
43 */ | |
44 UCharCharacterIterator(const UChar* textPtr, int32_t length); | |
45 | |
46 /** | |
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). | |
51 * The starting | |
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 | |
57 * @stable ICU 2.0 | |
58 */ | |
59 UCharCharacterIterator(const UChar* textPtr, int32_t length, | |
60 int32_t position); | |
61 | |
62 /** | |
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). | |
67 * The starting | |
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 | |
76 * @stable ICU 2.0 | |
77 */ | |
78 UCharCharacterIterator(const UChar* textPtr, int32_t length, | |
79 int32_t textBegin, | |
80 int32_t textEnd, | |
81 int32_t position); | |
82 | |
83 /** | |
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 | |
88 * @stable ICU 2.0 | |
89 */ | |
90 UCharCharacterIterator(const UCharCharacterIterator& that); | |
91 | |
92 /** | |
93 * Destructor. | |
94 * @stable ICU 2.0 | |
95 */ | |
96 virtual ~UCharCharacterIterator(); | |
97 | |
98 /** | |
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 | |
104 * @stable ICU 2.0 | |
105 */ | |
106 UCharCharacterIterator& | |
107 operator=(const UCharCharacterIterator& that); | |
108 | |
109 /** | |
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. | |
115 * @stable ICU 2.0 | |
116 */ | |
117 virtual UBool operator==(const ForwardCharacterIterator& that) const; | |
118 | |
119 /** | |
120 * Generates a hash code for this iterator. | |
121 * @return the hash code. | |
122 * @stable ICU 2.0 | |
123 */ | |
124 virtual int32_t hashCode(void) const; | |
125 | |
126 /** | |
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 | |
131 * @stable ICU 2.0 | |
132 */ | |
133 virtual CharacterIterator* clone(void) const; | |
134 | |
135 /** | |
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. | |
140 * @stable ICU 2.0 | |
141 */ | |
142 virtual UChar first(void); | |
143 | |
144 /** | |
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 | |
150 * @stable ICU 2.0 | |
151 */ | |
152 virtual UChar firstPostInc(void); | |
153 | |
154 /** | |
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 | |
161 * @stable ICU 2.0 | |
162 */ | |
163 virtual UChar32 first32(void); | |
164 | |
165 /** | |
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. | |
171 * @stable ICU 2.0 | |
172 */ | |
173 virtual UChar32 first32PostInc(void); | |
174 | |
175 /** | |
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. | |
180 * @stable ICU 2.0 | |
181 */ | |
182 virtual UChar last(void); | |
183 | |
184 /** | |
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. | |
189 * @stable ICU 2.0 | |
190 */ | |
191 virtual UChar32 last32(void); | |
192 | |
193 /** | |
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 | |
199 * @stable ICU 2.0 | |
200 */ | |
201 virtual UChar setIndex(int32_t position); | |
202 | |
203 /** | |
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 | |
212 * @stable ICU 2.0 | |
213 */ | |
214 virtual UChar32 setIndex32(int32_t position); | |
215 | |
216 /** | |
217 * Returns the code unit the iterator currently refers to. | |
218 * @return the code unit the iterator currently refers to. | |
219 * @stable ICU 2.0 | |
220 */ | |
221 virtual UChar current(void) const; | |
222 | |
223 /** | |
224 * Returns the code point the iterator currently refers to. | |
225 * @return the code point the iterator currently refers to. | |
226 * @stable ICU 2.0 | |
227 */ | |
228 virtual UChar32 current32(void) const; | |
229 | |
230 /** | |
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. | |
235 * @stable ICU 2.0 | |
236 */ | |
237 virtual UChar next(void); | |
238 | |
239 /** | |
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. | |
245 * @stable ICU 2.0 | |
246 */ | |
247 virtual UChar nextPostInc(void); | |
248 | |
249 /** | |
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. | |
257 * @stable ICU 2.0 | |
258 */ | |
259 virtual UChar32 next32(void); | |
260 | |
261 /** | |
262 * Gets the current code point for returning and advances to the next code poi
nt | |
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. | |
267 * @stable ICU 2.0 | |
268 */ | |
269 virtual UChar32 next32PostInc(void); | |
270 | |
271 /** | |
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 | |
275 * iteration. | |
276 * @return FALSE if there are no more code units or code points | |
277 * at or after the current position in the iteration range. | |
278 * @stable ICU 2.0 | |
279 */ | |
280 virtual UBool hasNext(); | |
281 | |
282 /** | |
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. | |
287 * @stable ICU 2.0 | |
288 */ | |
289 virtual UChar previous(void); | |
290 | |
291 /** | |
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. | |
296 * @stable ICU 2.0 | |
297 */ | |
298 virtual UChar32 previous32(void); | |
299 | |
300 /** | |
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 | |
304 * iteration. | |
305 * @return FALSE if there are no more code units or code points | |
306 * before the current position in the iteration range. | |
307 * @stable ICU 2.0 | |
308 */ | |
309 virtual UBool hasPrevious(); | |
310 | |
311 /** | |
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 forwar
d; | |
317 * a negative delta means backward. | |
318 * @param origin Origin enumeration {kStart, kCurrent, kEnd} | |
319 * @return the new position | |
320 * @stable ICU 2.0 | |
321 */ | |
322 virtual int32_t move(int32_t delta, EOrigin origin); | |
323 | |
324 /** | |
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 forwar
d; | |
330 * a negative delta means backward. | |
331 * @param origin Origin enumeration {kStart, kCurrent, kEnd} | |
332 * @return the new position | |
333 * @stable ICU 2.0 | |
334 */ | |
335 virtual int32_t move32(int32_t delta, EOrigin origin); | |
336 | |
337 /** | |
338 * Sets the iterator to iterate over a new range of text | |
339 * @stable ICU 2.0 | |
340 */ | |
341 void setText(const UChar* newText, int32_t newTextLength); | |
342 | |
343 /** | |
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. | |
348 * @stable ICU 2.0 | |
349 */ | |
350 virtual void getText(UnicodeString& result); | |
351 | |
352 /** | |
353 * Return a class ID for this class (not really public) | |
354 * @return a class ID for this class | |
355 * @stable ICU 2.0 | |
356 */ | |
357 static UClassID U_EXPORT2 getStaticClassID(void); | |
358 | |
359 /** | |
360 * Return a class ID for this object (not really public) | |
361 * @return a class ID for this object. | |
362 * @stable ICU 2.0 | |
363 */ | |
364 virtual UClassID getDynamicClassID(void) const; | |
365 | |
366 protected: | |
367 /** | |
368 * Protected constructor | |
369 * @stable ICU 2.0 | |
370 */ | |
371 UCharCharacterIterator(); | |
372 /** | |
373 * Protected member text | |
374 * @stable ICU 2.0 | |
375 */ | |
376 const UChar* text; | |
377 | |
378 }; | |
379 | |
380 U_NAMESPACE_END | |
381 #endif | |
OLD | NEW |