diff options
Diffstat (limited to 'src/corelib/tools/qiterator.qdoc')
| -rw-r--r-- | src/corelib/tools/qiterator.qdoc | 376 |
1 files changed, 126 insertions, 250 deletions
diff --git a/src/corelib/tools/qiterator.qdoc b/src/corelib/tools/qiterator.qdoc index 2c07dcf423..041fb0701d 100644 --- a/src/corelib/tools/qiterator.qdoc +++ b/src/corelib/tools/qiterator.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** 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$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \class QKeyValueIterator \inmodule QtCore @@ -89,8 +65,7 @@ \sa operator*() */ -/*! \fn template<typename Key, typename T, class Iterator> bool operator==(QKeyValueIterator<Key, T, Iterator> lhs, QKeyValueIterator<Key, T, Iterator> rhs) - \relates QKeyValueIterator +/*! \fn template<typename Key, typename T, class Iterator> bool QKeyValueIterator<Key, T, Iterator>::operator==(QKeyValueIterator<Key, T, Iterator> lhs, QKeyValueIterator<Key, T, Iterator> rhs) Returns \c true if \a rhs points to the same item as \a lhs otherwise returns \c false. @@ -98,8 +73,7 @@ \sa operator!=() */ -/*! \fn template<typename Key, typename T, class Iterator> bool operator!=(QKeyValueIterator<Key, T, Iterator> lhs, QKeyValueIterator<Key, T, Iterator> rhs) const - \relates QKeyValueIterator +/*! \fn template<typename Key, typename T, class Iterator> bool QKeyValueIterator<Key, T, Iterator>::operator!=(QKeyValueIterator<Key, T, Iterator> lhs, QKeyValueIterator<Key, T, Iterator> rhs) Returns \c true if \a rhs points to a different item than \a lhs otherwise returns \c false. @@ -110,7 +84,7 @@ /*! \fn template<typename Key, typename T, class Iterator> QKeyValueIterator &QKeyValueIterator<Key, T, Iterator>::operator++() - The prefix ++ operator (\c{++i}) advances the iterator to the + The prefix \c{++} operator (\c{++i}) advances the iterator to the next item in the container and returns the iterator. \note Advancing the iterator past its container's end() constitutes @@ -123,7 +97,7 @@ \overload - The postfix ++ operator (\c{i++}) advances the iterator to the + The postfix \c{++} operator (\c{i++}) advances the iterator to the next item in the container and returns the iterator's prior value. \note Advancing the iterator past its container's end() constitutes @@ -132,7 +106,7 @@ /*! \fn template<typename Key, typename T, class Iterator> QKeyValueIterator &QKeyValueIterator<Key, T, Iterator>::operator--() - The prefix -- operator (\c{--i}) backs the iterator up to the previous item + The prefix c{--} operator (\c{--i}) backs the iterator up to the previous item in the container and returns the iterator. \note Backing up an iterator to before its container's begin() constitutes @@ -145,7 +119,7 @@ \overload - The postfix -- operator (\c{i--}) backs the iterator up to the previous item + The postfix c{--} operator (\c{i--}) backs the iterator up to the previous item in the container and returns the iterator's prior value. \note Backing up an iterator to before its container's begin() constitutes @@ -163,9 +137,8 @@ \brief The QListIterator class provides a Java-style const iterator for QList and QQueue. QList has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. + iterators}. STL-style iterators are more efficient and should + be preferred. An alternative to using iterators is to use index positions. Most QList member functions take an index as their first parameter, @@ -214,10 +187,9 @@ \inmodule QtCore \brief The QSetIterator class provides a Java-style const iterator for QSet. - QSet supports both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. + QSet has both \l{Java-style iterators} and \l{STL-style + iterators}. STL-style iterators are more efficient and should + be preferred. QSetIterator\<T\> allows you to iterate over a QSet\<T\>. If you want to modify the set as you iterate over it, use @@ -241,12 +213,8 @@ \image javaiterators1.png - Here's how to iterate over the elements in reverse order: - - \snippet code/doc_src_qiterator.cpp 7 - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. + findNext() in a loop. Multiple iterators can be used on the same set. If the set is modified while a QSetIterator is active, the QSetIterator @@ -263,9 +231,8 @@ \brief The QMutableListIterator class provides a Java-style non-const iterator for QList, QQueue and QStack. QList has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. + iterators}. STL-style iterators are more efficient and should + be preferred. An alternative to using iterators is to use index positions. Most QList member functions take an index as their first parameter, @@ -330,9 +297,8 @@ \brief The QMutableSetIterator class provides a Java-style non-const iterator for QSet. QSet has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. + iterators}. STL-style iterators are more efficient and should + be preferred. QMutableSetIterator\<T\> allows you to iterate over a QSet\<T\> and remove items from the set as you iterate. If you don't want @@ -357,10 +323,6 @@ \image javaiterators1.png - Here's how to iterate over the elements in reverse order: - - \snippet code/doc_src_qiterator.cpp 18 - If you want to remove items as you iterate over the set, use remove(). @@ -423,40 +385,92 @@ */ /*! \fn template <class T> void QListIterator<T>::toBack() - \fn template <class T> void QSetIterator<T>::toBack() \fn template <class T> void QMutableListIterator<T>::toBack() - \fn template <class T> void QMutableSetIterator<T>::toBack() +//! [toBack] Moves the iterator to the back of the container (after the last item). +//! [toBack] \sa toFront(), previous() */ +/*! \fn template <class T> void QSetIterator<T>::toBack() + \include qiterator.qdoc toBack + \sa toFront() +*/ + +/*! \fn template <class T> void QMutableSetIterator<T>::toBack() + + Moves the iterator to the back of the container (after the last + item). + + \sa toFront() +*/ + /*! \fn template <class T> bool QListIterator<T>::hasNext() const - \fn template <class T> bool QSetIterator<T>::hasNext() const \fn template <class T> bool QMutableListIterator<T>::hasNext() const - \fn template <class T> bool QMutableSetIterator<T>::hasNext() const +//! [hasNext] Returns \c true if there is at least one item ahead of the iterator, i.e. the iterator is \e not at the back of the container; otherwise returns \c false. +//! [hasNext] \sa hasPrevious(), next() */ +/*! \fn template <class T> bool QSetIterator<T>::hasNext() const + \include qiterator.qdoc hasNext + \sa next() +*/ + +/*! \fn template <class T> bool QMutableSetIterator<T>::hasNext() const + + Returns \c true if there is at least one item ahead of the iterator, + i.e. the iterator is \e not at the back of the container; + otherwise returns \c false. + + \sa next() +*/ + /*! \fn template <class T> const T &QListIterator<T>::next() - \fn template <class T> const T &QSetIterator<T>::next() - \fn template <class T> const T &QMutableSetIterator<T>::next() +//! [next] Returns the next item and advances the iterator by one position. Calling this function on an iterator located at the back of the container leads to undefined results. +//! [next] \sa hasNext(), peekNext(), previous() */ +/*! + \fn template <class T> const T &QSetIterator<T>::next() + \include qiterator.qdoc next + \sa hasNext(), peekNext() +*/ + +/* \fn template <class T> const T &QMutableSetIterator<T>::next() + Returns the next item and advances the iterator by one position. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), peekNext() +*/ + +/*! \fn template <class T> const T &QMutableSetIterator<T>::next() + + Returns the next item and advances the iterator by one position. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), peekNext() +*/ + /*! \fn template <class T> T &QMutableListIterator<T>::next() Returns a reference to the next item, and advances the iterator @@ -469,40 +483,45 @@ */ /*! \fn template <class T> const T &QListIterator<T>::peekNext() const - \fn template <class T> const T &QSetIterator<T>::peekNext() const - \fn template <class T> const T &QMutableSetIterator<T>::peekNext() const +//! [peekNext] Returns the next item without moving the iterator. Calling this function on an iterator located at the back of the container leads to undefined results. +//! [peekNext] \sa hasNext(), next(), peekPrevious() */ -/*! \fn template <class T> T &QMutableListIterator<T>::peekNext() const +/*! + \fn template <class T> const T &QSetIterator<T>::peekNext() const + \include qiterator.qdoc peekNext + \sa hasNext(), next() +*/ - Returns a reference to the next item, without moving the iterator. +/*! + \fn template <class T> const T &QMutableSetIterator<T>::peekNext() const + + Returns the next item without moving the iterator. Calling this function on an iterator located at the back of the container leads to undefined results. - \sa hasNext(), next(), peekPrevious() + \sa hasNext(), next() */ -/*! - \fn template <class T> bool QMutableSetIterator<T>::hasPrevious() const - \obsolete Deprecated in order to align with std::unordered_set functionality. +/*! \fn template <class T> T &QMutableListIterator<T>::peekNext() const - Returns \c true if there is at least one item behind the iterator, - i.e. the iterator is \e not at the front of the container; - otherwise returns \c false. + Returns a reference to the next item, without moving the iterator. - \sa hasNext(), previous() + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), next(), peekPrevious() */ /*! \fn template <class T> bool QListIterator<T>::hasPrevious() const - \fn template <class T> bool QSetIterator<T>::hasPrevious() const \fn template <class T> bool QMutableListIterator<T>::hasPrevious() const Returns \c true if there is at least one item behind the iterator, @@ -512,21 +531,7 @@ \sa hasNext(), previous() */ -/*! - \fn template <class T> const T &QMutableSetIterator<T>::previous() - \obsolete Deprecated in order to align with std::unordered_set functionality. - - Returns the previous item and moves the iterator back by one - position. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - /*! \fn template <class T> const T &QListIterator<T>::previous() - \fn template <class T> const T &QSetIterator<T>::previous() Returns the previous item and moves the iterator back by one position. @@ -548,20 +553,7 @@ \sa hasPrevious(), peekPrevious(), next() */ -/*! - \fn template <class T> const T &QMutableSetIterator<T>::peekPrevious() const - \obsolete Deprecated in order to align with std::unordered_set functionality. - - Returns the previous item without moving the iterator. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() -*/ - /*! \fn template <class T> const T &QListIterator<T>::peekPrevious() const - \fn template <class T> const T &QSetIterator<T>::peekPrevious() const Returns the previous item without moving the iterator. @@ -583,7 +575,6 @@ /*! \fn template <class T> bool QMutableSetIterator<T>::findNext(const T &value) - \obsolete Deprecated in order to align with std::unordered_set functionality. Searches for \a value starting from the current iterator position forward. Returns \c true if \a value is found; otherwise returns \c false. @@ -591,28 +582,29 @@ After the call, if \a value was found, the iterator is positioned just after the matching item; otherwise, the iterator is positioned at the back of the container. - - \sa findPrevious() */ /*! \fn template <class T> bool QListIterator<T>::findNext(const T &value) - \fn template <class T> bool QSetIterator<T>::findNext(const T &value) \fn template <class T> bool QMutableListIterator<T>::findNext(const T &value) +//! [findNext] Searches for \a value starting from the current iterator position forward. Returns \c true if \a value is found; otherwise returns \c false. After the call, if \a value was found, the iterator is positioned just after the matching item; otherwise, the iterator is positioned at the back of the container. +//! [findNext] \sa findPrevious() */ +/*! \fn template <class T> bool QSetIterator<T>::findNext(const T &value) + \include qiterator.qdoc findNext +*/ + /*! \fn template <class T> bool QListIterator<T>::findPrevious(const T &value) - \fn template <class T> bool QSetIterator<T>::findPrevious(const T &value) \fn template <class T> bool QMutableListIterator<T>::findPrevious(const T &value) - \fn template <class T> bool QMutableSetIterator<T>::findPrevious(const T &value) Searches for \a value starting from the current iterator position backward. Returns \c true if \a value is found; otherwise returns @@ -639,7 +631,7 @@ /*! \fn template <class T> void QMutableSetIterator<T>::remove() Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). + traversal functions (next(), findNext()). Example: \snippet code/doc_src_qiterator.cpp 22 @@ -662,7 +654,6 @@ */ /*! \fn template <class T> const T &QMutableListIterator<T>::value() const - \fn template <class T> const T &QMutableSetIterator<T>::value() const Returns the value of the last item that was jumped over using one of the traversal functions (next(), previous(), findNext(), @@ -673,6 +664,12 @@ equivalent to peekNext(). */ +/*! \fn template <class T> const T &QMutableSetIterator<T>::value() const + + Returns the value of the last item that was jumped over using + next() or findNext(). +*/ + /*! \fn template <class T> T &QMutableListIterator<T>::value() \overload @@ -696,9 +693,8 @@ \brief The QMapIterator class provides a Java-style const iterator for QMap. QMap has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. + iterators}. STL-style iterators are more efficient and should + be preferred. QMapIterator\<Key, T\> allows you to iterate over a QMap. If you want to modify the map as you iterate over @@ -747,9 +743,8 @@ \brief The QMultiMapIterator class provides a Java-style const iterator for QMultiMap. QMultiMap has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. + iterators}. STL-style iterators are more efficient and should + be preferred. QMultiMapIterator\<Key, T\> allows you to iterate over a QMultiMap. If you want to modify the map as you iterate over @@ -789,7 +784,7 @@ continue iterating over the original map, ignoring the modified copy. - \sa QMutableMultiMapIterator, QMultiMapIterator::const_iterator + \sa QMutableMultiMapIterator */ /*! @@ -799,9 +794,8 @@ \brief The QHashIterator class provides a Java-style const iterator for QHash and QMultiHash. QHash has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. + iterators}. STL-style iterators are more efficient and should + be preferred. QHashIterator\<Key, T\> allows you to iterate over a QHash (or a QMultiHash). If you want to modify the hash as you iterate over @@ -847,9 +841,8 @@ \brief The QMutableMapIterator class provides a Java-style non-const iterator for QMap. QMap has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. + iterators}. STL-style iterators are more efficient and should + be preferred. QMutableMapIterator\<Key, T\> allows you to iterate over a QMap and modify the map. If you don't want to modify @@ -912,9 +905,8 @@ \brief The QMutableMultiMapIterator class provides a Java-style non-const iterator for QMultiMap. QMultiMap has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. + iterators}. STL-style iterators are more efficient and should + be preferred. QMutableMultiMapIterator\<Key, T\> allows you to iterate over a QMultiMap and modify the map. If you don't want to modify @@ -977,14 +969,12 @@ \brief The QMutableHashIterator class provides a Java-style non-const iterator for QHash and QMultiHash. QHash has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. + iterators}. STL-style iterators are more efficient and should + be preferred. QMutableHashIterator\<Key, T\> allows you to iterate over a QHash - (or a QMultiHash) and modify the hash. If you don't want to modify - the hash (or have a const QHash), use the slightly faster - QHashIterator instead. + and modify the hash. If you don't want to modify the hash (or have + a const QHash), use the slightly faster QHashIterator instead. The QMutableHashIterator constructor takes a QHash as argument. After construction, the iterator is located at the very beginning @@ -1139,7 +1129,7 @@ Calling this function on an iterator located at the back of the container leads to undefined results. - \sa hasNext(), peekNext(), previous() + \sa hasNext(), {QMapIterator::}{peekNext()}, previous() */ /*! \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::next() @@ -1185,7 +1175,7 @@ */ /*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::peekNext() const - \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekNext() + \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekNext() const Returns the next item without moving the iterator. @@ -1199,7 +1189,7 @@ */ /*! \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekNext() const - \fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::peekNext() + \fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::peekNext() const Returns a reference to the next item without moving the iterator. @@ -1252,28 +1242,6 @@ \sa hasNext(), previous() */ -/*! - \fn template <class Key, class T> bool QHashIterator<Key, T>::hasPrevious() const - \obsolete Deprecated in order to align with std::unordered_set functionality. - - Returns \c true if there is at least one item behind the iterator, - i.e. the iterator is \e not at the front of the container; - otherwise returns \c false. - - \sa hasNext(), previous() -*/ - -/*! - \fn template <class Key, class T> bool QMutableHashIterator<Key, T>::hasPrevious() const - \obsolete Deprecated in order to align with std::unordered_set functionality. - - Returns \c true if there is at least one item behind the iterator, - i.e. the iterator is \e not at the front of the container; - otherwise returns \c false. - - \sa hasNext(), previous() -*/ - /*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::previous() \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::previous() \fn template <class Key, class T> QMultiMapIterator<Key, T>::Item QMultiMapIterator<Key, T>::previous() @@ -1291,38 +1259,6 @@ \sa hasPrevious(), peekPrevious(), next() */ -/*! - \fn template <class Key, class T> QHashIterator<Key, T>::Item QHashIterator<Key, T>::previous() - \obsolete Deprecated in order to align with std::unordered_set functionality. - - Returns the previous item and moves the iterator back by one - position. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - -/*! - \fn template <class Key, class T> QMutableHashIterator<Key, T>::Item QMutableHashIterator<Key, T>::previous() - \obsolete Deprecated in order to align with std::unordered_set functionality. - - Returns the previous item and moves the iterator back by one - position. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - /*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::peekPrevious() const \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekPrevious() const \fn template <class Key, class T> QMultiMapIterator<Key, T>::Item QMultiMapIterator<Key, T>::peekPrevious() const @@ -1336,37 +1272,7 @@ Calling this function on an iterator located at the front of the container leads to undefined results. - \sa hasPrevious(), previous(), peekNext() -*/ - -/*! - \fn template <class Key, class T> QHashIterator<Key, T>::Item QHashIterator<Key, T>::peekPrevious() const - \obsolete Deprecated in order to align with std::unordered_set functionality. - - Returns the previous item without moving the iterator. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() -*/ - -/*! - \fn template <class Key, class T> QMutableHashIterator<Key, T>::Item QMutableHashIterator<Key, T>::peekPrevious() const - \obsolete Deprecated in order to align with std::unordered_set functionality. - - Returns the previous item without moving the iterator. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() + \sa hasPrevious(), previous(), {QMapIterator::}{peekNext()} */ /*! \fn template <class Key, class T> const T &QMapIterator<Key, T>::value() const @@ -1495,36 +1401,6 @@ \sa findNext() */ -/*! - \fn template <class Key, class T> bool QHashIterator<Key, T>::findPrevious(const T &value) - \obsolete Deprecated in order to align with std::unordered_set functionality. - - Searches for \a value starting from the current iterator position - backward. Returns \c true if a (key, value) pair with value \a value - is found; otherwise returns \c false. - - After the call, if \a value was found, the iterator is positioned - just before the matching item; otherwise, the iterator is - positioned at the front of the container. - - \sa findNext() -*/ - -/*! - \fn template <class Key, class T> bool QMutableHashIterator<Key, T>::findPrevious(const T &value) - \obsolete Deprecated in order to align with std::unordered_set functionality. - - Searches for \a value starting from the current iterator position - backward. Returns \c true if a (key, value) pair with value \a value - is found; otherwise returns \c false. - - After the call, if \a value was found, the iterator is positioned - just before the matching item; otherwise, the iterator is - positioned at the front of the container. - - \sa findNext() -*/ - /*! \fn template <class Key, class T> void QMutableMapIterator<Key, T>::remove() \fn template <class Key, class T> void QMutableMultiMapIterator<Key, T>::remove() |