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>bb10
Mårten Nordheim
parent
9d8e233284
commit
4c286d6f6c
|
|
@ -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
|
||||
*/
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue