QHash: Add note about reference/iterator invalidation

It is mentioned in the porting docs, and in the class description
of the _iterators_, but none of those are really natural places to
look for the behavior of the container.

So, let's add a general note/warning to the functions in question.

Fixes: QTBUG-124195
Pick-to: 6.7
Change-Id: Ic95e56f166df2c8067232dfb6b9cb5b05d6a4361
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

1 files changed, 104 insertions, 0 deletions

diff --git a/src/corelib/tools/qhash.cpp b/src/corelib/tools/qhash.cpp
index 374d448c8a..12e90daecf 100644
--- a/src/corelib/tools/qhash.cpp
+++ b/src/corelib/tools/qhash.cpp
@@ -2239,6 +2239,12 @@ size_t qHash(long double key, size_t seed) noexcept
     a \l{default-constructed value} into the hash with the \a key, and
     returns a reference to it.
 
+//! [qhash-iterator-invalidation-func-desc]
+    \warning Returned iterators/references should be considered invalidated
+    the next time you call a non-const function on the hash, or when the
+    hash is destroyed.
+//! [qhash-iterator-invalidation-func-desc]
+
     \sa insert(), value()
 */
 
@@ -2322,12 +2328,16 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first item in
     the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa constBegin(), end()
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::const_iterator QHash<Key, T>::begin() const
 
     \overload
+
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::const_iterator QHash<Key, T>::cbegin() const
@@ -2336,6 +2346,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
     in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa begin(), cend()
 */
 
@@ -2344,6 +2356,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
     in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa begin(), constEnd()
 */
 
@@ -2353,6 +2367,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first key
     in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa keyEnd()
 */
 
@@ -2361,12 +2377,16 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary item
     after the last item in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa begin(), constEnd()
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::const_iterator QHash<Key, T>::end() const
 
     \overload
+
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::const_iterator QHash<Key, T>::constEnd() const
@@ -2374,6 +2394,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
     item after the last item in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa constBegin(), end()
 */
 
@@ -2383,6 +2405,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
     item after the last item in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa cbegin(), end()
 */
 
@@ -2392,6 +2416,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
     item after the last key in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa keyBegin()
 */
 
@@ -2401,6 +2427,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first entry
     in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa keyValueEnd()
 */
 
@@ -2410,6 +2438,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
     entry after the last entry in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa keyValueBegin()
 */
 
@@ -2419,6 +2449,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
     in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa keyValueEnd()
 */
 
@@ -2428,6 +2460,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
     in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa keyValueBegin()
 */
 
@@ -2437,6 +2471,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
     entry after the last entry in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa keyValueBegin()
 */
 
@@ -2446,6 +2482,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
     entry after the last entry in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa constKeyValueBegin()
 */
 
@@ -2465,6 +2503,8 @@ size_t qHash(long double key, size_t seed) noexcept
     references to the ones in the hash. Specifically, mutating the value
     will modify the hash itself.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa QKeyValueIterator
 */
 
@@ -2482,6 +2522,8 @@ size_t qHash(long double key, size_t seed) noexcept
 
     \snippet code/src_corelib_tools_qhash.cpp 15
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa remove(), take(), find()
 */
 
@@ -2501,12 +2543,16 @@ size_t qHash(long double key, size_t seed) noexcept
 
     \snippet code/src_corelib_tools_qhash.cpp 16
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa value(), values()
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::const_iterator QHash<Key, T>::find(const Key &key) const
 
     \overload
+
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::const_iterator QHash<Key, T>::constFind(const Key &key) const
@@ -2518,6 +2564,8 @@ size_t qHash(long double key, size_t seed) noexcept
     If the hash contains no item with the \a key, the function
     returns constEnd().
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa find()
 */
 
@@ -2529,6 +2577,8 @@ size_t qHash(long double key, size_t seed) noexcept
     is replaced with \a value.
 
     Returns an iterator pointing to the new/updated element.
+
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
 */
 
 /*!
@@ -2540,6 +2590,8 @@ size_t qHash(long double key, size_t seed) noexcept
     construction.
 
     Returns an iterator pointing to the new element.
+
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
 */
 
 
@@ -2564,12 +2616,16 @@ size_t qHash(long double key, size_t seed) noexcept
 
     Returns a pair of iterators delimiting the range of values \c{[first, second)}, that
     are stored under \a key. If the range is empty then both iterators will be equal to end().
+
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
 */
 
 /*!
     \fn template <class Key, class T> std::pair<const_iterator, const_iterator> QMultiHash<Key, T>::equal_range(const Key &key) const
     \overload
     \since 5.7
+
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
 */
 
 /*! \typedef QHash::ConstIterator
@@ -3167,6 +3223,8 @@ size_t qHash(long double key, size_t seed) noexcept
 
     Returns an iterator pointing to the new/updated element.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa insert()
 */
 
@@ -3181,6 +3239,8 @@ size_t qHash(long double key, size_t seed) noexcept
 
     Returns an iterator pointing to the new element.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa replace()
 */
 
@@ -3199,6 +3259,8 @@ size_t qHash(long double key, size_t seed) noexcept
 
     Returns an iterator pointing to the new element.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa insert
 */
 
@@ -3215,6 +3277,8 @@ size_t qHash(long double key, size_t seed) noexcept
 
     Returns an iterator pointing to the new element.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa replace, emplace
 */
 
@@ -3281,6 +3345,8 @@ size_t qHash(long double key, size_t seed) noexcept
     If the hash contains multiple items with the \a key, this function returns
     a reference to the most recently inserted value.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa insert(), value()
 */
 
@@ -3433,12 +3499,16 @@ size_t qHash(long double key, size_t seed) noexcept
 
     If the hash contains multiple items with the \a key and \a value, the
     iterator returned points to the most recently inserted item.
+
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
 */
 
 /*!
     \fn template <class Key, class T> typename QMultiHash<Key, T>::const_iterator QMultiHash<Key, T>::find(const Key &key, const T &value) const
     \since 4.3
     \overload
+
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
 */
 
 /*!
@@ -3450,6 +3520,8 @@ size_t qHash(long double key, size_t seed) noexcept
 
     If the hash contains no such item, the function returns
     constEnd().
+
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
 */
 
 /*! \fn template <class Key, class T> QMultiHash<Key, T>::iterator QMultiHash<Key, T>::begin()
@@ -3457,12 +3529,16 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first item in
     the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa constBegin(), end()
 */
 
 /*! \fn template <class Key, class T> QMultiHash<Key, T>::const_iterator QMultiHash<Key, T>::begin() const
 
     \overload
+
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
 */
 
 /*! \fn template <class Key, class T> QMultiHash<Key, T>::const_iterator QMultiHash<Key, T>::cbegin() const
@@ -3471,6 +3547,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
     in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa begin(), cend()
 */
 
@@ -3479,6 +3557,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
     in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa begin(), constEnd()
 */
 
@@ -3488,6 +3568,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first key
     in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa keyEnd()
 */
 
@@ -3496,6 +3578,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary item
     after the last item in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa begin(), constEnd()
 */
 
@@ -3509,6 +3593,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
     item after the last item in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa constBegin(), end()
 */
 
@@ -3518,6 +3604,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
     item after the last item in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa cbegin(), end()
 */
 
@@ -3527,6 +3615,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
     item after the last key in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa keyBegin()
 */
 
@@ -3536,6 +3626,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first entry
     in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa keyValueEnd()
 */
 
@@ -3545,6 +3637,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
     entry after the last entry in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa keyValueBegin()
 */
 
@@ -3554,6 +3648,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
     in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa keyValueEnd()
 */
 
@@ -3563,6 +3659,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
     in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa keyValueBegin()
 */
 
@@ -3572,6 +3670,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
     entry after the last entry in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa keyValueBegin()
 */
 
@@ -3581,6 +3681,8 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
     entry after the last entry in the hash.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa constKeyValueBegin()
 */
 
@@ -3600,6 +3702,8 @@ size_t qHash(long double key, size_t seed) noexcept
     references to the ones in the hash. Specifically, mutating the value
     will modify the hash itself.
 
+    \include qhash.cpp qhash-iterator-invalidation-func-desc
+
     \sa QKeyValueIterator
 */