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