Revision control
++ // Copyright (C) 2014 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++ // Qt-Security score:insignificant reason:docs
++
++ /*!
++ \class QStringIterator
++ \since 5.3
++ \inmodule QtCore
++ \ingroup tools
++
++ \internal
++
++ \brief The QStringIterator class provides a Unicode-aware iterator over QString.
++
++ \reentrant
++
++ QStringIterator is a Java-like, bidirectional, const iterator over the contents of a
++ QString. Unlike QString's own iterators, which manage the individual UTF-16 code units,
++ QStringIterator is Unicode-aware: it will transparently handle the \e{surrogate pairs}
++ that may be present in a QString, and return the individual Unicode code points.
++
++ You can create a QStringIterator that iterates over a given
++ QStringView by passing the string to the QStringIterator's constructor:
++
++ \snippet code/src_corelib_text_qstringiterator.cpp 0
++
++ A newly created QStringIterator will point before the first position in the
++ string. It is possible to check whether the iterator can be advanced by
++ calling hasNext(), and actually advance it (and obtain the next code point)
++ by calling next():
++
++ \snippet code/src_corelib_text_qstringiterator.cpp 1
++
++ Similarly, the hasPrevious() and previous() functions can be used to iterate backwards.
++
++ The peekNext() and peekPrevious() functions will return the code point
++ respectively after and behind the iterator's current position, but unlike
++ next() and previous() they will not move the iterator.
++ Similarly, the advance() and recede() functions will move the iterator
++ respectively after and behind the iterator's current position, but they
++ will not return the code point the iterator has moved through.
++
++ \section1 Unicode Handling
++
++ QString and all of its functions work in terms of UTF-16 code units. Unicode code points
++ that fall outside the Basic Multilingual Plane (U+10000 to U+10FFFF) will therefore
++ be represented by \e{surrogate pairs} in a QString, that is, a sequence of two
++ UTF-16 code units that encode a single code point.
++
++ QStringIterator will automatically handle surrogate pairs inside a QString,
++ and return the correctly decoded code point, while also moving the iterator by
++ the right amount of code units to match the decoded code points.
++
++ For instance:
++
++ \snippet code/src_corelib_text_qstringiterator.cpp 2
++
++ If the iterator is not able to decode the next code point (or the previous
++ one, when iterating backwards), then it will return \c{0xFFFD}, that is,
++ Unicode's replacement character (see QChar::ReplacementCharacter).
++ It is possible to make QStringIterator return another value when it encounters
++ a decoding problem; please refer to the each function documentation for
++ more details.
++
++ \section1 Unchecked Iteration
++
++ It is possible to optimize iterating over a QString contents by skipping
++ some checks. This is in general not safe to do, because a QString is allowed
++ to contain malformed UTF-16 data; however, if we can trust a given QString,
++ then we can use the optimized \e{unchecked} functions.
++
++ QStringIterator provides the \e{unchecked} counterparts for next(),
++ peekNext(), advance(), previous(), peekPrevious(), and recede():
++ they're called, respectively,
++ nextUnchecked(), peekNextUnchecked(), advanceUnchecked(),
++ previousUnchecked(), peekPreviousUnchecked(), recedeUnchecked().
++ The counterparts work exactly like the original ones,
++ but they're faster as they're allowed to make certain assumptions about
++ the string contents.
++
++ \note please be extremely careful when using QStringIterator's unchecked functions,
++ as using them on a string containing malformed data leads to undefined behavior.
++
++ \sa QString, QChar
++ */
++
++ /*!
++ \fn QStringIterator::QStringIterator(QStringView string, qsizetype idx)
++
++ Constructs an iterator over the contents of \a string. The iterator will point
++ before position \a idx in the string.
++
++ The string view \a string must remain valid while the iterator is being used.
++ */
++
++ /*!
++ \fn QStringIterator::QStringIterator(const QChar *begin, const QChar *end)
++
++ Constructs an iterator which iterates over the range from \a begin to \a end.
++ The iterator will point before \a begin.
++
++ The range from \a begin to \a end must remain valid while the iterator is being used.
++ */
++
++ /*!
++ \fn QString::const_iterator QStringIterator::position() const
++
++ Returns the current position of the iterator.
++ */
++
++ /*!
++ \fn void QStringIterator::setPosition(QString::const_iterator position)
++
++ Sets the iterator's current position to \a position, which must be inside
++ of the iterable range.
++ */
++
++ /*!
++ \fn bool QStringIterator::hasNext() const
++
++ Returns true if the iterator has not reached the end of the valid iterable range
++ and therefore can move forward; false otherwise.
++
++ \sa next()
++ */
++
++ /*!
++ \fn void QStringIterator::advance()
++
++ Advances the iterator by one Unicode code point.
++
++ \note calling this function when the iterator is past the end of the iterable range
++ leads to undefined behavior.
++
++ \sa next(), hasNext()
++ */
++
++ /*!
++ \fn void QStringIterator::advanceUnchecked()
++
++ Advances the iterator by one Unicode code point.
++
++ \note calling this function when the iterator is past the end of the iterable range
++ or on a QString containing malformed UTF-16 data leads to undefined behavior.
++
++ \sa advance(), next(), hasNext()
++ */
++
++ /*!
++ \fn QStringIterator::peekNextUnchecked() const
++
++ Returns the Unicode code point that is immediately after the iterator's current
++ position. The current position is not changed.
++
++ \note calling this function when the iterator is past the end of the iterable range
++ or on a QString containing malformed UTF-16 data leads to undefined behavior.
++
++ \sa peekNext(), next(), hasNext()
++ */
++
++ /*!
++ \fn QStringIterator::peekNext(char32_t invalidAs = QChar::ReplacementCharacter) const
++
++ Returns the Unicode code point that is immediately after the iterator's current
++ position. The current position is not changed.
++
++ If the iterator is not able to decode the UTF-16 data after the iterator's current
++ position, this function returns \a invalidAs (by default, QChar::ReplacementCharacter,
++ which corresponds to \c{U+FFFD}).
++
++ \note calling this function when the iterator is past the end of the iterable range
++ leads to undefined behavior.
++
++ \sa next(), hasNext()
++ */
++
++ /*!
++ \fn QStringIterator::nextUnchecked()
++
++ Advances the iterator's current position by one Unicode code point,
++ and returns the Unicode code point that gets pointed by the iterator.
++
++ \note calling this function when the iterator is past the end of the iterable range
++ or on a QString containing malformed UTF-16 data leads to undefined behavior.
++
++ \sa next(), hasNext()
++ */
++
++ /*!
++ \fn QStringIterator::next(char32_t invalidAs = QChar::ReplacementCharacter)
++
++ Advances the iterator's current position by one Unicode code point,
++ and returns the Unicode code point that gets pointed by the iterator.
++
++ If the iterator is not able to decode the UTF-16 data at the iterator's current
++ position, this function returns \a invalidAs (by default, QChar::ReplacementCharacter,
++ which corresponds to \c{U+FFFD}).
++
++ \note calling this function when the iterator is past the end of the iterable range
++ leads to undefined behavior.
++
++ \sa peekNext(), hasNext()
++ */
++
++
++ /*!
++ \fn bool QStringIterator::hasPrevious() const
++
++ Returns true if the iterator is after the beginning of the valid iterable range
++ and therefore can move backwards; false otherwise.
++
++ \sa previous()
++ */
++
++ /*!
++ \fn void QStringIterator::recede()
++
++ Moves the iterator back by one Unicode code point.
++
++ \note calling this function when the iterator is before the beginning of the iterable range
++ leads to undefined behavior.
++
++ \sa previous(), hasPrevious()
++ */
++
++ /*!
++ \fn void QStringIterator::recedeUnchecked()
++
++ Moves the iterator back by one Unicode code point.
++
++ \note calling this function when the iterator is before the beginning of the iterable range
++ or on a QString containing malformed UTF-16 data leads to undefined behavior.
++
++ \sa recede(), previous(), hasPrevious()
++ */
++
++ /*!
++ \fn QStringIterator::peekPreviousUnchecked() const
++
++ Returns the Unicode code point that is immediately before the iterator's current
++ position. The current position is not changed.
++
++ \note calling this function when the iterator is before the beginning of the iterable range
++ or on a QString containing malformed UTF-16 data leads to undefined behavior.
++
++ \sa previous(), hasPrevious()
++ */
++
++ /*!
++ \fn QStringIterator::peekPrevious(char32_t invalidAs = QChar::ReplacementCharacter) const
++
++ Returns the Unicode code point that is immediately before the iterator's current
++ position. The current position is not changed.
++
++ If the iterator is not able to decode the UTF-16 data before the iterator's current
++ position, this function returns \a invalidAs (by default, QChar::ReplacementCharacter,
++ which corresponds to \c{U+FFFD}).
++
++ \note calling this function when the iterator is before the beginning of the iterable range
++ leads to undefined behavior.
++
++ \sa previous(), hasPrevious()
++ */
++
++ /*!
++ \fn QStringIterator::previousUnchecked()
++
++ Moves the iterator's current position back by one Unicode code point,
++ and returns the Unicode code point that gets pointed by the iterator.
++
++ \note calling this function when the iterator is before the beginning of the iterable range
++ or on a QString containing malformed UTF-16 data leads to undefined behavior.
++
++ \sa previous(), hasPrevious()
++ */
++
++ /*!
++ \fn QStringIterator::previous(char32_t invalidAs = QChar::ReplacementCharacter)
++
++ Moves the iterator's current position back by one Unicode code point,
++ and returns the Unicode code point that gets pointed by the iterator.
++
++ If the iterator is not able to decode the UTF-16 data at the iterator's current
++ position, this function returns \a invalidAs (by default, QChar::ReplacementCharacter,
++ which corresponds to \c{U+FFFD}).
++
++ \note calling this function when the iterator is before the beginning of the iterable range
++ leads to undefined behavior.
++
++ \sa peekPrevious(), hasPrevious()
++ */