1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 ******************************************************************************
5 *
6 *   Copyright (C) 1998-2005, International Business Machines
7 *   Corporation and others.  All Rights Reserved.
8 *
9 ******************************************************************************
10 *
11 * File schriter.h
12 *
13 * Modification History:
14 *
15 *   Date        Name        Description
16 *  05/05/99     stephen     Cleaned up.
17 ******************************************************************************
18 */
19 
20 #ifndef SCHRITER_H
21 #define SCHRITER_H
22 
23 #include "unicode/utypes.h"
24 #include "unicode/chariter.h"
25 #include "unicode/uchriter.h"
26 
27 /**
28  * \file
29  * \brief C++ API: String Character Iterator
30  */
31 
32 U_NAMESPACE_BEGIN
33 /**
34  * A concrete subclass of CharacterIterator that iterates over the
35  * characters (code units or code points) in a UnicodeString.
36  * It's possible not only to create an
37  * iterator that iterates over an entire UnicodeString, but also to
38  * create one that iterates over only a subrange of a UnicodeString
39  * (iterators over different subranges of the same UnicodeString don't
40  * compare equal).
41  * @see CharacterIterator
42  * @see ForwardCharacterIterator
43  * @stable ICU 2.0
44  */
45 class U_COMMON_API StringCharacterIterator : public UCharCharacterIterator {
46 public:
47   /**
48    * Create an iterator over the UnicodeString referred to by "textStr".
49    * The UnicodeString object is copied.
50    * The iteration range is the whole string, and the starting position is 0.
51    * @param textStr The unicode string used to create an iterator
52    * @stable ICU 2.0
53    */
54   StringCharacterIterator(const UnicodeString& textStr);
55 
56   /**
57    * Create an iterator over the UnicodeString referred to by "textStr".
58    * The iteration range is the whole string, and the starting
59    * position is specified by "textPos".  If "textPos" is outside the valid
60    * iteration range, the behavior of this object is undefined.
61    * @param textStr The unicode string used to create an iterator
62    * @param textPos The starting position of the iteration
63    * @stable ICU 2.0
64    */
65   StringCharacterIterator(const UnicodeString&    textStr,
66               int32_t              textPos);
67 
68   /**
69    * Create an iterator over the UnicodeString referred to by "textStr".
70    * The UnicodeString object is copied.
71    * The iteration range begins with the code unit specified by
72    * "textBegin" and ends with the code unit BEFORE the code unit specfied
73    * by "textEnd".  The starting position is specified by "textPos".  If
74    * "textBegin" and "textEnd" don't form a valid range on "text" (i.e.,
75    * textBegin >= textEnd or either is negative or greater than text.size()),
76    * or "textPos" is outside the range defined by "textBegin" and "textEnd",
77    * the behavior of this iterator is undefined.
78    * @param textStr    The unicode string used to create the StringCharacterIterator
79    * @param textBegin  The begin position of the iteration range
80    * @param textEnd    The end position of the iteration range
81    * @param textPos    The starting position of the iteration
82    * @stable ICU 2.0
83    */
84   StringCharacterIterator(const UnicodeString&    textStr,
85               int32_t              textBegin,
86               int32_t              textEnd,
87               int32_t              textPos);
88 
89   /**
90    * Copy constructor.  The new iterator iterates over the same range
91    * of the same string as "that", and its initial position is the
92    * same as "that"'s current position.
93    * The UnicodeString object in "that" is copied.
94    * @param that The StringCharacterIterator to be copied
95    * @stable ICU 2.0
96    */
97   StringCharacterIterator(const StringCharacterIterator&  that);
98 
99   /**
100    * Destructor.
101    * @stable ICU 2.0
102    */
103   virtual ~StringCharacterIterator();
104 
105   /**
106    * Assignment operator.  *this is altered to iterate over the same
107    * range of the same string as "that", and refers to the same
108    * character within that string as "that" does.
109    * @param that The object to be copied.
110    * @return the newly created object.
111    * @stable ICU 2.0
112    */
113   StringCharacterIterator&
114   operator=(const StringCharacterIterator&    that);
115 
116   /**
117    * Returns true if the iterators iterate over the same range of the
118    * same string and are pointing at the same character.
119    * @param that The ForwardCharacterIterator to be compared for equality
120    * @return true if the iterators iterate over the same range of the
121    * same string and are pointing at the same character.
122    * @stable ICU 2.0
123    */
124   virtual UBool          operator==(const ForwardCharacterIterator& that) const;
125 
126   /**
127    * Returns a new StringCharacterIterator 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 newly cloned object.
131    * @stable ICU 2.0
132    */
133   virtual CharacterIterator* clone(void) const;
134 
135   /**
136    * Sets the iterator to iterate over the provided string.
137    * @param newText The string to be iterated over
138    * @stable ICU 2.0
139    */
140   void setText(const UnicodeString& newText);
141 
142   /**
143    * Copies the UnicodeString under iteration into the UnicodeString
144    * referred to by "result".  Even if this iterator iterates across
145    * only a part of this string, the whole string is copied.
146    * @param result Receives a copy of the text under iteration.
147    * @stable ICU 2.0
148    */
149   virtual void            getText(UnicodeString& result);
150 
151   /**
152    * Return a class ID for this object (not really public)
153    * @return a class ID for this object.
154    * @stable ICU 2.0
155    */
156   virtual UClassID         getDynamicClassID(void) const;
157 
158   /**
159    * Return a class ID for this class (not really public)
160    * @return a class ID for this class
161    * @stable ICU 2.0
162    */
163   static UClassID   U_EXPORT2 getStaticClassID(void);
164 
165 protected:
166   /**
167    * Default constructor, iteration over empty string.
168    * @stable ICU 2.0
169    */
170   StringCharacterIterator();
171 
172   /**
173    * Sets the iterator to iterate over the provided string.
174    * @param newText The string to be iterated over
175    * @param newTextLength The length of the String
176    * @stable ICU 2.0
177    */
178   void setText(const char16_t* newText, int32_t newTextLength);
179 
180   /**
181    * Copy of the iterated string object.
182    * @stable ICU 2.0
183    */
184   UnicodeString            text;
185 
186 };
187 
188 U_NAMESPACE_END
189 #endif
190