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