From 77c2ac559fc9085608ec5a6995fcf4ec8446ec67 Mon Sep 17 00:00:00 2001 From: Kai Koehne Date: Mon, 13 Jul 2020 09:40:58 +0200 Subject: Doc: Mark API in Q[Mutable]HashIterator as deprecated The reverse iteration API got deprecated in code already in commit dbb54805f63f9e . Now also fix the documentation. Fixes: QTBUG-85482 Pick-to: 5.15 Change-Id: I3b575f60dabfe1005b9744d17c257da3e22817c5 Reviewed-by: Lars Knoll --- .../doc/snippets/code/doc_src_qiterator.cpp | 20 -- src/corelib/tools/qiterator.qdoc | 253 ++++++++++++++++++--- 2 files changed, 222 insertions(+), 51 deletions(-) (limited to 'src') diff --git a/src/corelib/doc/snippets/code/doc_src_qiterator.cpp b/src/corelib/doc/snippets/code/doc_src_qiterator.cpp index 265e4a724a..ed0cf9e329 100644 --- a/src/corelib/doc/snippets/code/doc_src_qiterator.cpp +++ b/src/corelib/doc/snippets/code/doc_src_qiterator.cpp @@ -195,16 +195,6 @@ while (i.hasNext()) { //! [29] -//! [30] -QHashIterator i(hash); -i.toBack(); -while (i.hasPrevious()) { - i.previous(); - qDebug() << i.key() << ": " << i.value(); -} -//! [30] - - //! [31] QHashIterator i(hash); while (i.findNext(widget)) { @@ -265,16 +255,6 @@ while (i.hasNext()) { //! [36] -//! [37] -QMutableHashIterator i(hash); -i.toBack(); -while (i.hasPrevious()) { - i.previous(); - qDebug() << i.key() << ": " << i.value(); -} -//! [37] - - //! [38] QMutableHashIterator i(hash); while (i.findNext(widget)) { diff --git a/src/corelib/tools/qiterator.qdoc b/src/corelib/tools/qiterator.qdoc index 174837ad08..4b61ae7778 100644 --- a/src/corelib/tools/qiterator.qdoc +++ b/src/corelib/tools/qiterator.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2020 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. @@ -792,12 +792,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 @@ -910,12 +906,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 @@ -987,9 +979,7 @@ */ /*! \fn template void QMapIterator::toBack() - \fn template void QHashIterator::toBack() \fn template void QMutableMapIterator::toBack() - \fn template void QMutableHashIterator::toBack() Moves the iterator to the back of the container (after the last item). @@ -997,10 +987,18 @@ \sa toFront(), previous() */ +/*! + \fn template void QHashIterator::toBack() + \fn template void QMutableHashIterator::toBack() + + Moves the iterator to the back of the container (after the last + item). + + \sa toFront() +*/ + /*! \fn template bool QMapIterator::hasNext() const - \fn template bool QHashIterator::hasNext() const \fn template bool QMutableMapIterator::hasNext() const - \fn template bool QMutableHashIterator::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 +1007,18 @@ \sa hasPrevious(), next() */ +/*! + \fn template bool QHashIterator::hasNext() const + \fn template bool QMutableHashIterator::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 QMapIterator::Item QMapIterator::next() - \fn template QHashIterator::Item QHashIterator::next() Returns the next item and advances the iterator by one position. @@ -1024,7 +1032,6 @@ */ /*! \fn template QMutableMapIterator::Item QMutableMapIterator::next() - \fn template QMutableHashIterator::Item QMutableHashIterator::next() Returns the next item and advances the iterator by one position. @@ -1037,8 +1044,35 @@ \sa hasNext(), peekNext(), previous() */ +/*! + \fn template QHashIterator::Item QHashIterator::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 QMutableHashIterator::Item QMutableHashIterator::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 QMapIterator::Item QMapIterator::peekNext() const - \fn template QHashIterator::Item QHashIterator::peekNext() const Returns the next item without moving the iterator. @@ -1052,7 +1086,6 @@ */ /*! \fn template QMutableMapIterator::Item QMutableMapIterator::peekNext() const - \fn template QMutableHashIterator::Item QMutableHashIterator::peekNext() const Returns a reference to the next item without moving the iterator. @@ -1065,10 +1098,58 @@ \sa hasNext(), next(), peekPrevious() */ +/*! + \fn template QHashIterator::Item QHashIterator::peekNext() const + + 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 back of the + container leads to undefined results. + + \sa hasNext(), next() +*/ + +/*! + \fn template QMutableHashIterator::Item QMutableHashIterator::peekNext() const + + 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 back of the + container leads to undefined results. + + \sa hasNext(), next() +*/ + /*! \fn template bool QMapIterator::hasPrevious() const - \fn template bool QHashIterator::hasPrevious() const \fn template bool QMutableMapIterator::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 bool QHashIterator::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 bool QMutableHashIterator::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; @@ -1078,7 +1159,23 @@ */ /*! \fn template QMapIterator::Item QMapIterator::previous() + \fn template QMutableMapIterator::Item QMutableMapIterator::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. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), peekPrevious(), next() +*/ + +/*! \fn template QHashIterator::Item QHashIterator::previous() + \obsolete Deprecated in order to align with std::unordered_set functionality. Returns the previous item and moves the iterator back by one position. @@ -1092,8 +1189,9 @@ \sa hasPrevious(), peekPrevious(), next() */ -/*! \fn template QMutableMapIterator::Item QMutableMapIterator::previous() +/*! \fn template QMutableHashIterator::Item QMutableHashIterator::previous() + \obsolete Deprecated in order to align with std::unordered_set functionality. Returns the previous item and moves the iterator back by one position. @@ -1108,7 +1206,22 @@ */ /*! \fn template QMapIterator::Item QMapIterator::peekPrevious() const + \fn template QMutableMapIterator::Item QMutableMapIterator::peekPrevious() const + + 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 QHashIterator::Item QHashIterator::peekPrevious() const + \obsolete Deprecated in order to align with std::unordered_set functionality. Returns the previous item without moving the iterator. @@ -1121,8 +1234,9 @@ \sa hasPrevious(), previous(), peekNext() */ -/*! \fn template QMutableMapIterator::Item QMutableMapIterator::peekPrevious() const +/*! \fn template QMutableHashIterator::Item QMutableHashIterator::peekPrevious() const + \obsolete Deprecated in order to align with std::unordered_set functionality. Returns the previous item without moving the iterator. @@ -1136,7 +1250,6 @@ */ /*! \fn template const T &QMapIterator::value() const - \fn template const T &QHashIterator::value() const Returns the value of the last item that was jumped over using one of the traversal functions (next(), previous(), findNext(), @@ -1151,7 +1264,6 @@ /*! \fn template const T &QMutableMapIterator::value() const - \fn template const T &QMutableHashIterator::value() const Returns the value of the last item that was jumped over using one of the traversal functions (next(), previous(), findNext(), @@ -1164,6 +1276,23 @@ \sa key(), setValue() */ +/*! \fn template const T &QHashIterator::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 const T &QMutableHashIterator::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 T &QMutableMapIterator::value() \fn template T &QMutableHashIterator::value() @@ -1175,9 +1304,7 @@ */ /*! \fn template const Key &QMapIterator::key() const - \fn template const Key &QHashIterator::key() const \fn template const Key &QMutableMapIterator::key() const - \fn template const Key &QMutableHashIterator::key() const Returns the key of the last item that was jumped over using one of the traversal functions (next(), previous(), findNext(), @@ -1190,10 +1317,17 @@ \sa value() */ +/*! \fn template const Key &QHashIterator::key() const + \fn template const Key &QMutableHashIterator::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 bool QMapIterator::findNext(const T &value) - \fn template bool QHashIterator::findNext(const T &value) \fn template bool QMutableMapIterator::findNext(const T &value) - \fn template bool QMutableHashIterator::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 +1340,50 @@ \sa findPrevious() */ +/*! \fn template bool QHashIterator::findNext(const T &value) + \fn template bool QMutableHashIterator::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 bool QMapIterator::findPrevious(const T &value) - \fn template bool QHashIterator::findPrevious(const T &value) \fn template bool QMutableMapIterator::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 + 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 bool QHashIterator::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 bool QMutableHashIterator::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 @@ -1223,7 +1397,6 @@ */ /*! \fn template void QMutableMapIterator::remove() - \fn template void QMutableHashIterator::remove() Removes the last item that was jumped over using one of the traversal functions (next(), previous(), findNext(), findPrevious()). @@ -1231,8 +1404,15 @@ \sa setValue() */ +/*! \fn template void QMutableHashIterator::remove() + + Removes the last item that was jumped over using one of the + traversal functions (next(), findNext()). + + \sa setValue() +*/ + /*! \fn template void QMutableMapIterator::setValue(const T &value) - \fn template void QMutableHashIterator::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 +1422,14 @@ \sa key(), value(), remove() */ + +/*! + \fn template void QMutableHashIterator::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() +*/ -- cgit v1.2.3