Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
qstringiterator.qdoc
Go to the documentation of this file.
1// Copyright (C) 2014 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \class QStringIterator
6 \since 5.3
7 \inmodule QtCore
8 \ingroup tools
9
10 \internal
11
12 \brief The QStringIterator class provides a Unicode-aware iterator over QString.
13
14 \reentrant
15
16 QStringIterator is a Java-like, bidirectional, const iterator over the contents of a
17 QString. Unlike QString's own iterators, which manage the individual UTF-16 code units,
18 QStringIterator is Unicode-aware: it will transparently handle the \e{surrogate pairs}
19 that may be present in a QString, and return the individual Unicode code points.
20
21 You can create a QStringIterator that iterates over a given
22 QStringView by passing the string to the QStringIterator's constructor:
23
24 \snippet code/src_corelib_text_qstringiterator.cpp 0
25
26 A newly created QStringIterator will point before the first position in the
27 string. It is possible to check whether the iterator can be advanced by
28 calling hasNext(), and actually advance it (and obtain the next code point)
29 by calling next():
30
31 \snippet code/src_corelib_text_qstringiterator.cpp 1
32
33 Similarly, the hasPrevious() and previous() functions can be used to iterate backwards.
34
35 The peekNext() and peekPrevious() functions will return the code point
36 respectively after and behind the iterator's current position, but unlike
37 next() and previous() they will not move the iterator.
38 Similarly, the advance() and recede() functions will move the iterator
39 respectively after and behind the iterator's current position, but they
40 will not return the code point the iterator has moved through.
41
42 \section1 Unicode Handling
43
44 QString and all of its functions work in terms of UTF-16 code units. Unicode code points
45 that fall outside the Basic Multilingual Plane (U+10000 to U+10FFFF) will therefore
46 be represented by \e{surrogate pairs} in a QString, that is, a sequence of two
47 UTF-16 code units that encode a single code point.
48
49 QStringIterator will automatically handle surrogate pairs inside a QString,
50 and return the correctly decoded code point, while also moving the iterator by
51 the right amount of code units to match the decoded code points.
52
53 For instance:
54
55 \snippet code/src_corelib_text_qstringiterator.cpp 2
56
57 If the iterator is not able to decode the next code point (or the previous
58 one, when iterating backwards), then it will return \c{0xFFFD}, that is,
59 Unicode's replacement character (see QChar::ReplacementCharacter).
60 It is possible to make QStringIterator return another value when it encounters
61 a decoding problem; please refer to the each function documentation for
62 more details.
63
64 \section1 Unchecked Iteration
65
66 It is possible to optimize iterating over a QString contents by skipping
67 some checks. This is in general not safe to do, because a QString is allowed
68 to contain malformed UTF-16 data; however, if we can trust a given QString,
69 then we can use the optimized \e{unchecked} functions.
70
71 QStringIterator provides the \e{unchecked} counterparts for next(),
72 peekNext(), advance(), previous(), peekPrevious(), and recede():
73 they're called, respectively,
74 nextUnchecked(), peekNextUnchecked(), advanceUnchecked(),
75 previousUnchecked(), peekPreviousUnchecked(), recedeUnchecked().
76 The counterparts work exactly like the original ones,
77 but they're faster as they're allowed to make certain assumptions about
78 the string contents.
79
80 \note please be extremely careful when using QStringIterator's unchecked functions,
81 as using them on a string containing malformed data leads to undefined behavior.
82
83 \sa QString, QChar
84*/
85
86/*!
87 \fn QStringIterator::QStringIterator(QStringView string, qsizetype idx)
88
89 Constructs an iterator over the contents of \a string. The iterator will point
90 before position \a idx in the string.
91
92 The string view \a string must remain valid while the iterator is being used.
93*/
94
95/*!
96 \fn QStringIterator::QStringIterator(const QChar *begin, const QChar *end)
97
98 Constructs an iterator which iterates over the range from \a begin to \a end.
99 The iterator will point before \a begin.
100
101 The range from \a begin to \a end must remain valid while the iterator is being used.
102*/
103
104/*!
105 \fn QString::const_iterator QStringIterator::position() const
106
107 Returns the current position of the iterator.
108*/
109
110/*!
111 \fn void QStringIterator::setPosition(QString::const_iterator position)
112
113 Sets the iterator's current position to \a position, which must be inside
114 of the iterable range.
115*/
116
117/*!
118 \fn bool QStringIterator::hasNext() const
119
120 Returns true if the iterator has not reached the end of the valid iterable range
121 and therefore can move forward; false otherwise.
122
123 \sa next()
124*/
125
126/*!
127 \fn void QStringIterator::advance()
128
129 Advances the iterator by one Unicode code point.
130
131 \note calling this function when the iterator is past the end of the iterable range
132 leads to undefined behavior.
133
134 \sa next(), hasNext()
135*/
136
137/*!
138 \fn void QStringIterator::advanceUnchecked()
139
140 Advances the iterator by one Unicode code point.
141
142 \note calling this function when the iterator is past the end of the iterable range
143 or on a QString containing malformed UTF-16 data leads to undefined behavior.
144
145 \sa advance(), next(), hasNext()
146*/
147
148/*!
149 \fn QStringIterator::peekNextUnchecked() const
150
151 Returns the Unicode code point that is immediately after the iterator's current
152 position. The current position is not changed.
153
154 \note calling this function when the iterator is past the end of the iterable range
155 or on a QString containing malformed UTF-16 data leads to undefined behavior.
156
157 \sa peekNext(), next(), hasNext()
158*/
159
160/*!
161 \fn QStringIterator::peekNext(char32_t invalidAs = QChar::ReplacementCharacter) const
162
163 Returns the Unicode code point that is immediately after the iterator's current
164 position. The current position is not changed.
165
166 If the iterator is not able to decode the UTF-16 data after the iterator's current
167 position, this function returns \a invalidAs (by default, QChar::ReplacementCharacter,
168 which corresponds to \c{U+FFFD}).
169
170 \note calling this function when the iterator is past the end of the iterable range
171 leads to undefined behavior.
172
173 \sa next(), hasNext()
174*/
175
176/*!
177 \fn QStringIterator::nextUnchecked()
178
179 Advances the iterator's current position by one Unicode code point,
180 and returns the Unicode code point that gets pointed by the iterator.
181
182 \note calling this function when the iterator is past the end of the iterable range
183 or on a QString containing malformed UTF-16 data leads to undefined behavior.
184
185 \sa next(), hasNext()
186*/
187
188/*!
189 \fn QStringIterator::next(char32_t invalidAs = QChar::ReplacementCharacter)
190
191 Advances the iterator's current position by one Unicode code point,
192 and returns the Unicode code point that gets pointed by the iterator.
193
194 If the iterator is not able to decode the UTF-16 data at the iterator's current
195 position, this function returns \a invalidAs (by default, QChar::ReplacementCharacter,
196 which corresponds to \c{U+FFFD}).
197
198 \note calling this function when the iterator is past the end of the iterable range
199 leads to undefined behavior.
200
201 \sa peekNext(), hasNext()
202*/
203
204
205/*!
206 \fn bool QStringIterator::hasPrevious() const
207
208 Returns true if the iterator is after the beginning of the valid iterable range
209 and therefore can move backwards; false otherwise.
210
211 \sa previous()
212*/
213
214/*!
215 \fn void QStringIterator::recede()
216
217 Moves the iterator back by one Unicode code point.
218
219 \note calling this function when the iterator is before the beginning of the iterable range
220 leads to undefined behavior.
221
222 \sa previous(), hasPrevious()
223*/
224
225/*!
226 \fn void QStringIterator::recedeUnchecked()
227
228 Moves the iterator back by one Unicode code point.
229
230 \note calling this function when the iterator is before the beginning of the iterable range
231 or on a QString containing malformed UTF-16 data leads to undefined behavior.
232
233 \sa recede(), previous(), hasPrevious()
234*/
235
236/*!
237 \fn QStringIterator::peekPreviousUnchecked() const
238
239 Returns the Unicode code point that is immediately before the iterator's current
240 position. The current position is not changed.
241
242 \note calling this function when the iterator is before the beginning of the iterable range
243 or on a QString containing malformed UTF-16 data leads to undefined behavior.
244
245 \sa previous(), hasPrevious()
246*/
247
248/*!
249 \fn QStringIterator::peekPrevious(char32_t invalidAs = QChar::ReplacementCharacter) const
250
251 Returns the Unicode code point that is immediately before the iterator's current
252 position. The current position is not changed.
253
254 If the iterator is not able to decode the UTF-16 data before the iterator's current
255 position, this function returns \a invalidAs (by default, QChar::ReplacementCharacter,
256 which corresponds to \c{U+FFFD}).
257
258 \note calling this function when the iterator is before the beginning of the iterable range
259 leads to undefined behavior.
260
261 \sa previous(), hasPrevious()
262*/
263
264/*!
265 \fn QStringIterator::previousUnchecked()
266
267 Moves the iterator's current position back by one Unicode code point,
268 and returns the Unicode code point that gets pointed by the iterator.
269
270 \note calling this function when the iterator is before the beginning of the iterable range
271 or on a QString containing malformed UTF-16 data leads to undefined behavior.
272
273 \sa previous(), hasPrevious()
274*/
275
276/*!
277 \fn QStringIterator::previous(char32_t invalidAs = QChar::ReplacementCharacter)
278
279 Moves the iterator's current position back by one Unicode code point,
280 and returns the Unicode code point that gets pointed by the iterator.
281
282 If the iterator is not able to decode the UTF-16 data at the iterator's current
283 position, this function returns \a invalidAs (by default, QChar::ReplacementCharacter,
284 which corresponds to \c{U+FFFD}).
285
286 \note calling this function when the iterator is before the beginning of the iterable range
287 leads to undefined behavior.
288
289 \sa peekPrevious(), hasPrevious()
290*/