From 93e22bd21f08c5733974c273bf901ca62487c75a Mon Sep 17 00:00:00 2001 From: Volker Hilsheimer Date: Wed, 23 Sep 2020 00:33:56 +0200 Subject: [PATCH] Documentation: purge QSet and QHash members that no longer exist QMutableSet/HashIterator can not walk backwards, neither can the STL iterator. When function documentation was shared with other iterator types, move it into separate section to avoid linking to incorrect see-alsos. Remove or fix other member function documentation that had errors, e.g. in parameter types after move to qsizetype. Change-Id: Ic7f97a295eff63ee748998b10f08a160706fa650 Reviewed-by: Lars Knoll --- .../doc/snippets/code/doc_src_qiterator.cpp | 9 - src/corelib/tools/qiterator.qdoc | 218 ++++---------- src/corelib/tools/qset.qdoc | 271 +----------------- 3 files changed, 55 insertions(+), 443 deletions(-) diff --git a/src/corelib/doc/snippets/code/doc_src_qiterator.cpp b/src/corelib/doc/snippets/code/doc_src_qiterator.cpp index 2ee618d394..44801dda09 100644 --- a/src/corelib/doc/snippets/code/doc_src_qiterator.cpp +++ b/src/corelib/doc/snippets/code/doc_src_qiterator.cpp @@ -118,15 +118,6 @@ while (i.hasNext()) qDebug() << i.next(); //! [17] - -//! [18] -QMutableSetIterator i(set); -i.toBack(); -while (i.hasPrevious()) - qDebug() << i.previous(); -//! [18] - - //! [19] QMutableListIterator i(list); while (i.hasNext()) { diff --git a/src/corelib/tools/qiterator.qdoc b/src/corelib/tools/qiterator.qdoc index 2c07dcf423..eacc504557 100644 --- a/src/corelib/tools/qiterator.qdoc +++ b/src/corelib/tools/qiterator.qdoc @@ -357,10 +357,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(). @@ -425,7 +421,6 @@ /*! \fn template void QListIterator::toBack() \fn template void QSetIterator::toBack() \fn template void QMutableListIterator::toBack() - \fn template void QMutableSetIterator::toBack() Moves the iterator to the back of the container (after the last item). @@ -433,10 +428,17 @@ \sa toFront(), previous() */ +/*! \fn template void QMutableSetIterator::toBack() + + Moves the iterator to the back of the container (after the last + item). + + \sa toFront() +*/ + /*! \fn template bool QListIterator::hasNext() const \fn template bool QSetIterator::hasNext() const \fn template bool QMutableListIterator::hasNext() const - \fn template bool QMutableSetIterator::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; @@ -445,9 +447,17 @@ \sa hasPrevious(), next() */ +/*! \fn template bool QMutableSetIterator::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 const T &QListIterator::next() \fn template const T &QSetIterator::next() - \fn template const T &QMutableSetIterator::next() Returns the next item and advances the iterator by one position. @@ -457,6 +467,25 @@ \sa hasNext(), peekNext(), previous() */ +/* \fn template const T &QMutableSetIterator::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 const T &QMutableSetIterator::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 T &QMutableListIterator::next() Returns a reference to the next item, and advances the iterator @@ -470,7 +499,6 @@ /*! \fn template const T &QListIterator::peekNext() const \fn template const T &QSetIterator::peekNext() const - \fn template const T &QMutableSetIterator::peekNext() const Returns the next item without moving the iterator. @@ -480,6 +508,17 @@ \sa hasNext(), next(), peekPrevious() */ +/*! + \fn template const T &QMutableSetIterator::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() +*/ + /*! \fn template T &QMutableListIterator::peekNext() const Returns a reference to the next item, without moving the iterator. @@ -490,17 +529,6 @@ \sa hasNext(), next(), peekPrevious() */ -/*! - \fn template bool QMutableSetIterator::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 QListIterator::hasPrevious() const \fn template bool QSetIterator::hasPrevious() const \fn template bool QMutableListIterator::hasPrevious() const @@ -512,19 +540,6 @@ \sa hasNext(), previous() */ -/*! - \fn template const T &QMutableSetIterator::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 const T &QListIterator::previous() \fn template const T &QSetIterator::previous() @@ -548,18 +563,6 @@ \sa hasPrevious(), peekPrevious(), next() */ -/*! - \fn template const T &QMutableSetIterator::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 const T &QListIterator::peekPrevious() const \fn template const T &QSetIterator::peekPrevious() const @@ -583,7 +586,6 @@ /*! \fn template bool QMutableSetIterator::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,8 +593,6 @@ 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 bool QListIterator::findNext(const T &value) @@ -612,7 +612,6 @@ /*! \fn template bool QListIterator::findPrevious(const T &value) \fn template bool QSetIterator::findPrevious(const T &value) \fn template bool QMutableListIterator::findPrevious(const T &value) - \fn template bool QMutableSetIterator::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 +638,7 @@ /*! \fn template void QMutableSetIterator::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 +661,6 @@ */ /*! \fn template const T &QMutableListIterator::value() const - \fn template const T &QMutableSetIterator::value() const Returns the value of the last item that was jumped over using one of the traversal functions (next(), previous(), findNext(), @@ -673,6 +671,12 @@ equivalent to peekNext(). */ +/*! \fn template const T &QMutableSetIterator::value() const + + Returns the value of the last item that was jumped over using + next() or findNext(). +*/ + /*! \fn template T &QMutableListIterator::value() \overload @@ -1252,28 +1256,6 @@ \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; - otherwise returns \c false. - - \sa hasNext(), previous() -*/ - /*! \fn template QMapIterator::Item QMapIterator::previous() \fn template QMutableMapIterator::Item QMutableMapIterator::previous() \fn template QMultiMapIterator::Item QMultiMapIterator::previous() @@ -1291,38 +1273,6 @@ \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. - - 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 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. - - 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 QMapIterator::Item QMapIterator::peekPrevious() const \fn template QMutableMapIterator::Item QMutableMapIterator::peekPrevious() const \fn template QMultiMapIterator::Item QMultiMapIterator::peekPrevious() const @@ -1339,36 +1289,6 @@ \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. - - 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 QMutableHashIterator::Item QMutableHashIterator::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 const T &QMapIterator::value() const \fn template const T &QMultiMapIterator::value() const @@ -1495,36 +1415,6 @@ \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 - 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 void QMutableMapIterator::remove() \fn template void QMutableMultiMapIterator::remove() diff --git a/src/corelib/tools/qset.qdoc b/src/corelib/tools/qset.qdoc index b6aae2c7ca..a98ce6cb06 100644 --- a/src/corelib/tools/qset.qdoc +++ b/src/corelib/tools/qset.qdoc @@ -185,7 +185,7 @@ \sa reserve(), squeeze() */ -/*! \fn template void QSet::reserve(int size) +/*! \fn template void QSet::reserve(qsizetype size) Ensures that the set's internal hash table consists of at least \a size buckets. @@ -278,12 +278,6 @@ \sa remove(), find() */ -/*! - \fn template QSet::iterator QSet::erase(iterator pos) - \since 4.2 - \overload -*/ - /*! \fn template QSet::const_iterator QSet::find(const T &value) const \since 4.2 @@ -398,58 +392,6 @@ \sa constBegin(), end() */ -/*! \fn template QSet::reverse_iterator QSet::rbegin() - \obsolete Deprecated in order to align with std::unordered_set functionality. - \since 5.6 - - Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to the first - item in the set, in reverse order. - - \sa begin(), crbegin(), rend() -*/ - -/*! \fn template QSet::const_reverse_iterator QSet::rbegin() const - \obsolete Deprecated in order to align with std::unordered_set functionality. - \since 5.6 - \overload -*/ - -/*! \fn template QSet::const_reverse_iterator QSet::crbegin() const - \obsolete Deprecated in order to align with std::unordered_set functionality. - \since 5.6 - - Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to the first - item in the set, in reverse order. - - \sa begin(), rbegin(), rend() -*/ - -/*! \fn template QSet::reverse_iterator QSet::rend() - \obsolete Deprecated in order to align with std::unordered_set functionality. - \since 5.6 - - Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past - the last item in the set, in reverse order. - - \sa end(), crend(), rbegin() -*/ - -/*! \fn template QSet::const_reverse_iterator QSet::rend() const - \obsolete Deprecated in order to align with std::unordered_set functionality. - \since 5.6 - \overload -*/ - -/*! \fn template QSet::const_reverse_iterator QSet::crend() const - \obsolete Deprecated in order to align with std::unordered_set functionality. - \since 5.6 - - Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to one - past the last item in the set, in reverse order. - - \sa end(), rend(), rbegin() -*/ - /*! \typedef QSet::Iterator \since 4.2 @@ -511,40 +453,6 @@ Typedef for T. Provided for STL compatibility. */ -/*! \typedef QSet::reverse_iterator - \since 5.6 - \obsolete Deprecated in order to align with std::unordered_set functionality. - - The QSet::reverse_iterator typedef provides an STL-style non-const - reverse iterator for QSet. - - It is simply a typedef for \c{std::reverse_iterator}. - - \warning Iterators on implicitly shared containers do not work - exactly like STL-iterators. You should avoid copying a container - while iterators are active on that container. For more information, - read \l{Implicit sharing iterator problem}. - - \sa QSet::rbegin(), QSet::rend(), QSet::const_reverse_iterator, QSet::iterator -*/ - -/*! \typedef QSet::const_reverse_iterator - \since 5.6 - \obsolete Deprecated in order to align with std::unordered_set functionality. - - The QSet::const_reverse_iterator typedef provides an STL-style const - reverse iterator for QSet. - - It is simply a typedef for \c{std::reverse_iterator}. - - \warning Iterators on implicitly shared containers do not work - exactly like STL-iterators. You should avoid copying a container - while iterators are active on that container. For more information, - read \l{Implicit sharing iterator problem}. - - \sa QSet::rbegin(), QSet::rend(), QSet::reverse_iterator, QSet::const_iterator -*/ - /*! \fn template QSet::insert(const T &value) @@ -927,196 +835,19 @@ current item. */ -/*! - \fn template QSet::iterator &QSet::iterator::operator--() - \obsolete This operator is deprecated in order to align with std::unordered_set functionality. - - The prefix -- operator (\c{--it}) makes the preceding item - current and returns an iterator to the new current item. - - Calling this function on QSet::begin() leads to undefined - results. - - \sa operator++() -*/ - -/*! - \fn template QSet::const_iterator &QSet::const_iterator::operator--() - \obsolete This operator is deprecated in order to align with std::unordered_set functionality. - - The prefix -- operator (\c{--it}) makes the preceding item - current and returns an iterator to the new current item. - - Calling this function on QSet::begin() leads to undefined - results. - - \sa operator++() -*/ - -/*! - \fn template QSet::iterator QSet::iterator::operator--(int) - \obsolete This operator is deprecated in order to align with std::unordered_set functionality. - - \overload - - The postfix -- operator (\c{it--}) makes the preceding item - current and returns an iterator to the previously current item. -*/ - -/*! - \fn template QSet::const_iterator QSet::const_iterator::operator--(int) - \obsolete This operator is deprecated in order to align with std::unordered_set functionality. - - \overload - - The postfix -- operator (\c{it--}) makes the preceding item - current and returns an iterator to the previously current item. -*/ - -/*! - \fn template QSet::iterator QSet::iterator::operator+(int j) const - \obsolete This operator is deprecated in order to align with std::unordered_set functionality. - - Returns an iterator to the item at \a j positions forward from - this iterator. (If \a j is negative, the iterator goes backward.) - - This operation can be slow for large \a j values. - - \sa operator-() -*/ - -/*! - \fn template QSet::const_iterator QSet::const_iterator::operator+(int j) const - \obsolete This operator is deprecated in order to align with std::unordered_set functionality. - - Returns an iterator to the item at \a j positions forward from - this iterator. (If \a j is negative, the iterator goes backward.) - - This operation can be slow for large \a j values. - - \sa operator-() -*/ - -/*! - \fn template QSet::iterator QSet::iterator::operator-(int j) const - \obsolete This operator is deprecated in order to align with std::unordered_set functionality. - - Returns an iterator to the item at \a j positions backward from - this iterator. (If \a j is negative, the iterator goes forward.) - - This operation can be slow for large \a j values. - - \sa operator+() -*/ - -/*! - \fn template QSet::const_iterator QSet::const_iterator::operator-(int j) const - \obsolete This operator is deprecated in order to align with std::unordered_set functionality. - - Returns an iterator to the item at \a j positions backward from - this iterator. (If \a j is negative, the iterator goes forward.) - - This operation can be slow for large \a j values. - - \sa operator+() -*/ - -/*! - \fn template QSet::iterator &QSet::iterator::operator+=(int j) - \obsolete This operator is deprecated in order to align with std::unordered_set functionality. - - Advances the iterator by \a j items. (If \a j is negative, the - iterator goes backward.) - - This operation can be slow for large \a j values. - - \sa operator-=(), operator+() - -*/ - -/*! - \fn template QSet::const_iterator &QSet::const_iterator::operator+=(int j) - \obsolete This operator is deprecated in order to align with std::unordered_set functionality. - - Advances the iterator by \a j items. (If \a j is negative, the - iterator goes backward.) - - This operation can be slow for large \a j values. - - \sa operator-=(), operator+() -*/ - -/*! - \fn template QSet::iterator &QSet::iterator::operator-=(int j) - \obsolete This operator is deprecated in order to align with std::unordered_set functionality. - - Makes the iterator go back by \a j items. (If \a j is negative, - the iterator goes forward.) - - This operation can be slow for large \a j values. - - \sa operator+=(), operator-() -*/ - -/*! - \fn template QSet::const_iterator &QSet::const_iterator::operator-=(int j) - \obsolete This operator is deprecated in order to align with std::unordered_set functionality. - - Makes the iterator go back by \a j items. (If \a j is negative, - the iterator goes forward.) - - This operation can be slow for large \a j values. - - \sa operator+=(), operator-() -*/ - -/*! \fn template QList QSet::toList() const - - Returns a new QList containing the elements in the set. The - order of the elements in the QList is undefined. - - Example: - - \snippet code/doc_src_qset.cpp 13 - - \include containers-range-constructor.qdocinc - - \sa fromList(), QList::fromSet() -*/ - /*! \fn template QList QSet::values() const Returns a new QList containing the elements in the set. The order of the elements in the QList is undefined. - This is the same as toList(). - \include containers-range-constructor.qdocinc This function creates a new list, in \l {linear time}. The time and memory use that entails can be avoided by iterating from \l constBegin() to \l constEnd(). - - \sa fromList(), QList::fromSet() */ -/*! \fn template QSet QSet::fromList(const QList &list) - - Returns a new QSet object containing the data contained in \a - list. Since QSet doesn't allow duplicates, the resulting QSet - might be smaller than the \a list, because QList can contain - duplicates. - - Example: - - \snippet code/doc_src_qset.cpp 14 - - \include containers-range-constructor.qdocinc - - \sa toList(), QList::toSet() -*/ - /*! \fn template QDataStream &operator<<(QDataStream &out, const QSet &set) \relates QSet