| /**************************************************************************** |
| ** |
| ** Copyright (C) 2014 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com> |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \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_tools_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_tools_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_tools_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 uint 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 uint QStringIterator::peekNext(uint 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 uint 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 uint QStringIterator::next(uint 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 uint 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 uint QStringIterator::peekPrevious(uint 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 uint 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 uint QStringIterator::previous(uint 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() |
| */ |