1/*
2******************************************************************************
3*
4*   Copyright (C) 1998-2005, International Business Machines
5*   Corporation and others.  All Rights Reserved.
6*
7******************************************************************************
8*
9* File schriter.h
10*
11* Modification History:
12*
13*   Date        Name        Description
14*  05/05/99     stephen     Cleaned up.
15******************************************************************************
16*/
17
18#ifndef SCHRITER_H
19#define SCHRITER_H
20
21#include "unicode/utypes.h"
22#include "unicode/chariter.h"
23#include "unicode/uchriter.h"
24
25/**
26 * \file
27 * \brief C++ API: String Character Iterator
28 */
29
30U_NAMESPACE_BEGIN
31/**
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
38 * compare equal).
39 * @see CharacterIterator
40 * @see ForwardCharacterIterator
41 * @stable ICU 2.0
42 */
43class U_COMMON_API StringCharacterIterator : public UCharCharacterIterator {
44public:
45  /**
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
50   * @stable ICU 2.0
51   */
52  StringCharacterIterator(const UnicodeString& textStr);
53
54  /**
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
61   * @stable ICU 2.0
62   */
63  StringCharacterIterator(const UnicodeString&    textStr,
64              int32_t              textPos);
65
66  /**
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
80   * @stable ICU 2.0
81   */
82  StringCharacterIterator(const UnicodeString&    textStr,
83              int32_t              textBegin,
84              int32_t              textEnd,
85              int32_t              textPos);
86
87  /**
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
93   * @stable ICU 2.0
94   */
95  StringCharacterIterator(const StringCharacterIterator&  that);
96
97  /**
98   * Destructor.
99   * @stable ICU 2.0
100   */
101  virtual ~StringCharacterIterator();
102
103  /**
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.
109   * @stable ICU 2.0
110   */
111  StringCharacterIterator&
112  operator=(const StringCharacterIterator&    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 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   * 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.
129   * @stable ICU 2.0
130   */
131  virtual CharacterIterator* clone(void) const;
132
133  /**
134   * Sets the iterator to iterate over the provided string.
135   * @param newText The string to be iterated over
136   * @stable ICU 2.0
137   */
138  void setText(const UnicodeString& newText);
139
140  /**
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.
145   * @stable ICU 2.0
146   */
147  virtual void            getText(UnicodeString& result);
148
149  /**
150   * Return a class ID for this object (not really public)
151   * @return a class ID for this object.
152   * @stable ICU 2.0
153   */
154  virtual UClassID         getDynamicClassID(void) const;
155
156  /**
157   * Return a class ID for this class (not really public)
158   * @return a class ID for this class
159   * @stable ICU 2.0
160   */
161  static UClassID   U_EXPORT2 getStaticClassID(void);
162
163protected:
164  /**
165   * Default constructor, iteration over empty string.
166   * @stable ICU 2.0
167   */
168  StringCharacterIterator();
169
170  /**
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
174   * @stable ICU 2.0
175   */
176  void setText(const UChar* newText, int32_t newTextLength);
177
178  /**
179   * Copy of the iterated string object.
180   * @stable ICU 2.0
181   */
182  UnicodeString            text;
183
184};
185
186U_NAMESPACE_END
187#endif
188