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
19U_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 */
33class U_COMMON_API UCharCharacterIterator : public CharacterIterator {
34public:
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 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.
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 forward;
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 forward;
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
366protected:
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
380U_NAMESPACE_END
381#endif
382