codekingpro/portable-devtools

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 UBool          operator==(const ForwardCharacterIterator& that) const;
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;
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);
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;
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   * Sets the iterator to iterate over the provided string.
177   * @param newText The string to be iterated over
178   * @param newTextLength The length of the String
179   * @stable ICU 2.0
180   */
181  void setText(const char16_t* newText, int32_t newTextLength);
182
183  /**
184   * Copy of the iterated string object.
185   * @stable ICU 2.0
186   */
187  UnicodeString            text;
188
189};
190
191U_NAMESPACE_END
192
193#endif /* U_SHOW_CPLUSPLUS_API */
194
195#endif
196