diff options
Diffstat (limited to 'src/corelib/tools/qiterator.qdoc')
-rw-r--r-- | src/corelib/tools/qiterator.qdoc | 160 |
1 files changed, 73 insertions, 87 deletions
diff --git a/src/corelib/tools/qiterator.qdoc b/src/corelib/tools/qiterator.qdoc index eacc504557..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 @@ -419,15 +385,21 @@ */ /*! \fn template <class T> void QListIterator<T>::toBack() - \fn template <class T> void QSetIterator<T>::toBack() \fn template <class T> void QMutableListIterator<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 @@ -437,16 +409,22 @@ */ /*! \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 +//! [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, @@ -457,16 +435,23 @@ */ /*! \fn template <class T> const T &QListIterator<T>::next() - \fn template <class T> const T &QSetIterator<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. @@ -498,17 +483,24 @@ */ /*! \fn template <class T> const T &QListIterator<T>::peekNext() const - \fn template <class T> const T &QSetIterator<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> const T &QSetIterator<T>::peekNext() const + \include qiterator.qdoc peekNext + \sa hasNext(), next() +*/ + +/*! \fn template <class T> const T &QMutableSetIterator<T>::peekNext() const Returns the next item without moving the iterator. @@ -530,7 +522,6 @@ */ /*! \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, @@ -541,7 +532,6 @@ */ /*! \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,7 +554,6 @@ */ /*! \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. @@ -596,21 +585,25 @@ */ /*! \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) Searches for \a value starting from the current iterator position @@ -700,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 @@ -751,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 @@ -793,7 +784,7 @@ continue iterating over the original map, ignoring the modified copy. - \sa QMutableMultiMapIterator, QMultiMapIterator::const_iterator + \sa QMutableMultiMapIterator */ /*! @@ -803,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 @@ -851,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 @@ -916,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 @@ -981,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 @@ -1143,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() @@ -1189,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. @@ -1203,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. @@ -1286,7 +1272,7 @@ 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 |