diff options
Diffstat (limited to 'src/corelib/tools/qiterator.qdoc')
| -rw-r--r-- | src/corelib/tools/qiterator.qdoc | 610 |
1 files changed, 404 insertions, 206 deletions
diff --git a/src/corelib/tools/qiterator.qdoc b/src/corelib/tools/qiterator.qdoc index 174837ad08..041fb0701d 100644 --- a/src/corelib/tools/qiterator.qdoc +++ b/src/corelib/tools/qiterator.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 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, @@ -210,22 +183,13 @@ */ /*! - \class QVectorIterator - \inmodule QtCore - \brief QVectorIterator is an alias for QListIterator. - - Please see the QListIterator documentation for details. -*/ - -/*! \class QSetIterator \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 @@ -249,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 @@ -271,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, @@ -331,14 +290,6 @@ */ /*! - \class QMutableVectorIterator - \inmodule QtCore - \brief QMutableVectorIterator is an alias for QMutableListIterator. - - Please see the QMutableListIterator documentation for details. -*/ - -/*! \class QMutableSetIterator \inmodule QtCore \since 4.2 @@ -346,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 @@ -373,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(). @@ -439,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 @@ -485,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, @@ -528,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. @@ -564,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. @@ -599,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. @@ -607,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 @@ -655,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 @@ -678,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(), @@ -689,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 @@ -709,15 +690,14 @@ \class QMapIterator \inmodule QtCore - \brief The QMapIterator class provides a Java-style const iterator for QMap and QMultiMap. + \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 (or a - QMultiMap). If you want to modify the map as you iterate over + QMapIterator\<Key, T\> allows you to iterate over a QMap. + If you want to modify the map as you iterate over it, use QMutableMapIterator instead. The QMapIterator constructor takes a QMap as argument. After @@ -758,15 +738,64 @@ */ /*! + \class QMultiMapIterator + \inmodule QtCore + + \brief The QMultiMapIterator class provides a Java-style const iterator for QMultiMap. + QMultiMap has both \l{Java-style iterators} and \l{STL-style + 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 + it, use QMutableMultiMapIterator instead. + + The QMultiMapIterator constructor takes a QMultiMap as argument. After + construction, the iterator is located at the very beginning of + the map (before the first item). Here's how to iterate over all + the elements sequentially: + + \snippet code/doc_src_qiterator.cpp 26multi + + The next() function returns the next item in the map and + advances the iterator. The key() and value() functions return the + key and value of the last item that was jumped over. + + Unlike STL-style iterators, Java-style iterators point \e between + items rather than directly \e at items. The first call to next() + advances the iterator to the position between the first and + second item, and returns the first item; the second call to + next() advances the iterator to the position between the second + and third item; and so on. + + \image javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet code/doc_src_qiterator.cpp 27multi + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. For example: + + \snippet code/doc_src_qiterator.cpp 28multi + + Multiple iterators can be used on the same map. If the map is + modified while a QMultiMapIterator is active, the QMultiMapIterator will + continue iterating over the original map, ignoring the modified + copy. + + \sa QMutableMultiMapIterator +*/ + +/*! \class QHashIterator \inmodule QtCore \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 @@ -792,12 +821,8 @@ \image javaiterators1.png - Here's how to iterate over the elements in reverse order: - - \snippet code/doc_src_qiterator.cpp 30 - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. For example: + findNext() in a loop. For example: \snippet code/doc_src_qiterator.cpp 31 @@ -813,15 +838,14 @@ \class QMutableMapIterator \inmodule QtCore - \brief The QMutableMapIterator class provides a Java-style non-const iterator for QMap and QMultiMap. + \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 - (or a QMultiMap) and modify the map. If you don't want to modify + and modify the map. If you don't want to modify the map (or have a const QMap), use the slightly faster QMapIterator instead. @@ -875,20 +899,82 @@ */ /*! + \class QMutableMultiMapIterator + \inmodule QtCore + + \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}. 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 + the map (or have a const QMultiMap), use the slightly faster + QMultiMapIterator instead. + + The QMutableMultiMapIterator constructor takes a QMultiMap as argument. + After construction, the iterator is located at the very beginning + of the map (before the first item). Here's how to iterate over + all the elements sequentially: + + \snippet code/doc_src_qiterator.cpp 32multi + + The next() function returns the next item in the map and + advances the iterator. The key() and value() functions return the + key and value of the last item that was jumped over. + + Unlike STL-style iterators, Java-style iterators point \e between + items rather than directly \e at items. The first call to next() + advances the iterator to the position between the first and + second item, and returns the first item; the second call to + next() advances the iterator to the position between the second + and third item; and so on. + + \image javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet code/doc_src_qiterator.cpp 33multi + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. For example: + + \snippet code/doc_src_qiterator.cpp 34multi + + If you want to remove items as you iterate over the map, use + remove(). If you want to modify the value of an item, use + setValue(). + + Example: + + \snippet code/doc_src_qiterator.cpp 35multi + + The example removes all (key, value) pairs where the key and the + value are the same. + + Only one mutable iterator can be active on a given map at any + time. Furthermore, no changes should be done directly to the map + while the iterator is active (as opposed to through the + iterator), since this could invalidate the iterator and lead to + undefined behavior. + + \sa QMultiMapIterator, QMultiMap::iterator +*/ + +/*! \class QMutableHashIterator \inmodule QtCore \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 @@ -910,12 +996,8 @@ \image javaiterators1.png - Here's how to iterate over the elements in reverse order: - - \snippet code/doc_src_qiterator.cpp 37 - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. For example: + findNext() in a loop. For example: \snippet code/doc_src_qiterator.cpp 38 @@ -941,6 +1023,8 @@ /*! \fn template <class Key, class T> QMapIterator<Key, T>::QMapIterator(const QMap<Key, T> &map) \fn template <class Key, class T> QMutableMapIterator<Key, T>::QMutableMapIterator(QMap<Key, T> &map) + \fn template <class Key, class T> QMultiMapIterator<Key, T>::QMultiMapIterator(const QMultiMap<Key, T> &map) + \fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::QMutableMultiMapIterator(QMultiMap<Key, T> &map) Constructs an iterator for traversing \a map. The iterator is set to be at the front of the map (before the first item). @@ -959,6 +1043,8 @@ /*! \fn template <class Key, class T> QMapIterator &QMapIterator<Key, T>::operator=(const QMap<Key, T> &map) \fn template <class Key, class T> QMutableMapIterator &QMutableMapIterator<Key, T>::operator=(QMap<Key, T> &map) + \fn template <class Key, class T> QMultiMapIterator &QMultiMapIterator<Key, T>::operator=(const QMultiMap<Key, T> &map) + \fn template <class Key, class T> QMutableMultiMapIterator &QMutableMultiMapIterator<Key, T>::operator=(QMultiMap<Key, T> &map) Makes the iterator operate on \a map. The iterator is set to be at the front of the map (before the first item). @@ -976,8 +1062,10 @@ */ /*! \fn template <class Key, class T> void QMapIterator<Key, T>::toFront() + \fn template <class Key, class T> void QMultiMapIterator<Key, T>::toFront() \fn template <class Key, class T> void QHashIterator<Key, T>::toFront() \fn template <class Key, class T> void QMutableMapIterator<Key, T>::toFront() + \fn template <class Key, class T> void QMutableMultiMapIterator<Key, T>::toFront() \fn template <class Key, class T> void QMutableHashIterator<Key, T>::toFront() Moves the iterator to the front of the container (before the @@ -987,9 +1075,9 @@ */ /*! \fn template <class Key, class T> void QMapIterator<Key, T>::toBack() - \fn template <class Key, class T> void QHashIterator<Key, T>::toBack() + \fn template <class Key, class T> void QMultiMapIterator<Key, T>::toBack() \fn template <class Key, class T> void QMutableMapIterator<Key, T>::toBack() - \fn template <class Key, class T> void QMutableHashIterator<Key, T>::toBack() + \fn template <class Key, class T> void QMutableMultiMapIterator<Key, T>::toBack() Moves the iterator to the back of the container (after the last item). @@ -997,10 +1085,20 @@ \sa toFront(), previous() */ +/*! + \fn template <class Key, class T> void QHashIterator<Key, T>::toBack() + \fn template <class Key, class T> void QMutableHashIterator<Key, T>::toBack() + + Moves the iterator to the back of the container (after the last + item). + + \sa toFront() +*/ + /*! \fn template <class Key, class T> bool QMapIterator<Key, T>::hasNext() const - \fn template <class Key, class T> bool QHashIterator<Key, T>::hasNext() const + \fn template <class Key, class T> bool QMultiMapIterator<Key, T>::hasNext() const \fn template <class Key, class T> bool QMutableMapIterator<Key, T>::hasNext() const - \fn template <class Key, class T> bool QMutableHashIterator<Key, T>::hasNext() const + \fn template <class Key, class T> bool QMutableMultiMapIterator<Key, 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; @@ -1009,8 +1107,19 @@ \sa hasPrevious(), next() */ +/*! + \fn template <class Key, class T> bool QHashIterator<Key, T>::hasNext() const + \fn template <class Key, class T> bool QMutableHashIterator<Key, 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 Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::next() - \fn template <class Key, class T> QHashIterator<Key, T>::Item QHashIterator<Key, T>::next() + \fn template <class Key, class T> QMultiMapIterator<Key, T>::Item QMultiMapIterator<Key, T>::next() Returns the next item and advances the iterator by one position. @@ -1020,11 +1129,11 @@ 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() - \fn template <class Key, class T> QMutableHashIterator<Key, T>::Item QMutableHashIterator<Key, T>::next() + \fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::next() Returns the next item and advances the iterator by one position. @@ -1037,8 +1146,36 @@ \sa hasNext(), peekNext(), previous() */ +/*! + \fn template <class Key, class T> QHashIterator<Key, T>::Item QHashIterator<Key, T>::next() + + Returns the next item and advances the iterator 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 back of the + container leads to undefined results. + + \sa hasNext(), peekNext() +*/ + +/*! + \fn template <class Key, class T> QMutableHashIterator<Key, T>::Item QMutableHashIterator<Key, T>::next() + + Returns the next item and advances the iterator 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 back of the + container leads to undefined results. + + \sa hasNext(), peekNext() +*/ + /*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::peekNext() const - \fn template <class Key, class T> QHashIterator<Key, T>::Item QHashIterator<Key, T>::peekNext() const + \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekNext() const Returns the next item without moving the iterator. @@ -1052,7 +1189,7 @@ */ /*! \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekNext() const - \fn template <class Key, class T> QMutableHashIterator<Key, T>::Item QMutableHashIterator<Key, T>::peekNext() const + \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. @@ -1065,52 +1202,53 @@ \sa hasNext(), next(), peekPrevious() */ -/*! \fn template <class Key, class T> bool QMapIterator<Key, T>::hasPrevious() const - \fn template <class Key, class T> bool QHashIterator<Key, T>::hasPrevious() const - \fn template <class Key, class T> bool QMutableMapIterator<Key, T>::hasPrevious() const - \fn template <class Key, class T> bool QMutableHashIterator<Key, T>::hasPrevious() 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. - - \sa hasNext(), previous() -*/ - -/*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::previous() - \fn template <class Key, class T> QHashIterator<Key, T>::Item QHashIterator<Key, T>::previous() +/*! + \fn template <class Key, class T> QHashIterator<Key, T>::Item QHashIterator<Key, T>::peekNext() const - Returns the previous item and moves the iterator back by one - position. + Returns the next 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 + Calling this function on an iterator located at the back of the container leads to undefined results. - \sa hasPrevious(), peekPrevious(), next() + \sa hasNext(), next() */ -/*! \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::previous() - \fn template <class Key, class T> QMutableHashIterator<Key, T>::Item QMutableHashIterator<Key, T>::previous() +/*! + \fn template <class Key, class T> QMutableHashIterator<Key, T>::Item QMutableHashIterator<Key, T>::peekNext() const - Returns the previous item and moves the iterator back by one - position. + Returns a reference to the next 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 + Calling this function on an iterator located at the back of the container leads to undefined results. - \sa hasPrevious(), peekPrevious(), next() + \sa hasNext(), next() */ -/*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::peekPrevious() const - \fn template <class Key, class T> QHashIterator<Key, T>::Item QHashIterator<Key, T>::peekPrevious() const +/*! \fn template <class Key, class T> bool QMapIterator<Key, T>::hasPrevious() const + \fn template <class Key, class T> bool QMultiMapIterator<Key, T>::hasPrevious() const + \fn template <class Key, class T> bool QMutableMapIterator<Key, T>::hasPrevious() const + \fn template <class Key, class T> bool QMutableMultiMapIterator<Key, T>::hasPrevious() const - Returns the previous item without moving the iterator. + 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() + \fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::previous() + + 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. @@ -1118,11 +1256,13 @@ Calling this function on an iterator located at the front of the container leads to undefined results. - \sa hasPrevious(), previous(), peekNext() + \sa hasPrevious(), peekPrevious(), next() */ -/*! \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekPrevious() const - \fn template <class Key, class T> QMutableHashIterator<Key, T>::Item QMutableHashIterator<Key, T>::peekPrevious() const +/*! \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 + \fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::peekPrevious() const Returns the previous item without moving the iterator. @@ -1132,11 +1272,11 @@ 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 - \fn template <class Key, class T> const T &QHashIterator<Key, T>::value() const + \fn template <class Key, class T> const T &QMultiMapIterator<Key, T>::value() const Returns the value of the last item that was jumped over using one of the traversal functions (next(), previous(), findNext(), @@ -1151,7 +1291,7 @@ /*! \fn template <class Key, class T> const T &QMutableMapIterator<Key, T>::value() const - \fn template <class Key, class T> const T &QMutableHashIterator<Key, T>::value() const + \fn template <class Key, class T> const T &QMutableMultiMapIterator<Key, T>::value() const Returns the value of the last item that was jumped over using one of the traversal functions (next(), previous(), findNext(), @@ -1164,8 +1304,26 @@ \sa key(), setValue() */ +/*! \fn template <class Key, class T> const T &QHashIterator<Key, T>::value() const + + Returns the value of the last item that was jumped over using one + of the traversal functions (next(), findNext()). + + \sa key() +*/ + +/*! + \fn template <class Key, class T> const T &QMutableHashIterator<Key, T>::value() const + + Returns the value of the last item that was jumped over using one + of the traversal functions (next(), findNext()). + + \sa key(), setValue() +*/ + /*! \fn template <class Key, class T> T &QMutableMapIterator<Key, T>::value() + \fn template <class Key, class T> T &QMutableMultiMapIterator<Key, T>::value() \fn template <class Key, class T> T &QMutableHashIterator<Key, T>::value() \overload @@ -1175,9 +1333,9 @@ */ /*! \fn template <class Key, class T> const Key &QMapIterator<Key, T>::key() const - \fn template <class Key, class T> const Key &QHashIterator<Key, T>::key() const \fn template <class Key, class T> const Key &QMutableMapIterator<Key, T>::key() const - \fn template <class Key, class T> const Key &QMutableHashIterator<Key, T>::key() const + \fn template <class Key, class T> const Key &QMultiMapIterator<Key, T>::key() const + \fn template <class Key, class T> const Key &QMutableMultiMapIterator<Key, T>::key() const Returns the key of the last item that was jumped over using one of the traversal functions (next(), previous(), findNext(), @@ -1190,10 +1348,19 @@ \sa value() */ +/*! \fn template <class Key, class T> const Key &QHashIterator<Key, T>::key() const + \fn template <class Key, class T> const Key &QMutableHashIterator<Key, T>::key() const + + Returns the key of the last item that was jumped over using one + of the traversal functions (next(), findNext()). + + \sa value() +*/ + /*! \fn template <class Key, class T> bool QMapIterator<Key, T>::findNext(const T &value) - \fn template <class Key, class T> bool QHashIterator<Key, T>::findNext(const T &value) \fn template <class Key, class T> bool QMutableMapIterator<Key, T>::findNext(const T &value) - \fn template <class Key, class T> bool QMutableHashIterator<Key, T>::findNext(const T &value) + \fn template <class Key, class T> bool QMultiMapIterator<Key, T>::findNext(const T &value) + \fn template <class Key, class T> bool QMutableMultiMapIterator<Key, T>::findNext(const T &value) Searches for \a value starting from the current iterator position forward. Returns \c true if a (key, value) pair with value \a value @@ -1206,10 +1373,22 @@ \sa findPrevious() */ +/*! \fn template <class Key, class T> bool QHashIterator<Key, T>::findNext(const T &value) + \fn template <class Key, class T> bool QMutableHashIterator<Key, T>::findNext(const T &value) + + Searches for \a value starting from the current iterator position + forward. 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 after the matching item; otherwise, the iterator is + positioned at the back of the container. +*/ + /*! \fn template <class Key, class T> bool QMapIterator<Key, T>::findPrevious(const T &value) - \fn template <class Key, class T> bool QHashIterator<Key, T>::findPrevious(const T &value) \fn template <class Key, class T> bool QMutableMapIterator<Key, T>::findPrevious(const T &value) - \fn template <class Key, class T> bool QMutableHashIterator<Key, T>::findPrevious(const T &value) + \fn template <class Key, class T> bool QMultiMapIterator<Key, T>::findPrevious(const T &value) + \fn template <class Key, class T> bool QMutableMultiMapIterator<Key, T>::findPrevious(const T &value) Searches for \a value starting from the current iterator position backward. Returns \c true if a (key, value) pair with value \a value @@ -1223,7 +1402,7 @@ */ /*! \fn template <class Key, class T> void QMutableMapIterator<Key, T>::remove() - \fn template <class Key, class T> void QMutableHashIterator<Key, T>::remove() + \fn template <class Key, class T> void QMutableMultiMapIterator<Key, T>::remove() Removes the last item that was jumped over using one of the traversal functions (next(), previous(), findNext(), findPrevious()). @@ -1231,8 +1410,16 @@ \sa setValue() */ +/*! \fn template <class Key, class T> void QMutableHashIterator<Key, T>::remove() + + Removes the last item that was jumped over using one of the + traversal functions (next(), findNext()). + + \sa setValue() +*/ + /*! \fn template <class Key, class T> void QMutableMapIterator<Key, T>::setValue(const T &value) - \fn template <class Key, class T> void QMutableHashIterator<Key, T>::setValue(const T &value) + \fn template <class Key, class T> void QMutableMultiMapIterator<Key, T>::setValue(const T &value) Replaces the value of the last item that was jumped over using one of the traversal functions with \a value. @@ -1242,3 +1429,14 @@ \sa key(), value(), remove() */ + +/*! + \fn template <class Key, class T> void QMutableHashIterator<Key, T>::setValue(const T &value) + + Replaces the value of the last item that was jumped over using + one of the traversal functions with \a value. + + The traversal functions are next() and findNext(). + + \sa key(), value(), remove() +*/ |