Revision control
++ // Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \class QMap
++ \inmodule QtCore
++ \brief The QMap class is a template class that provides an associative array.
++ \compares equality
++
++ \ingroup tools
++ \ingroup shared
++ \ingroup containers
++
++ \reentrant
++
++ QMap\<Key, T\> is one of Qt's generic \l{container classes}, where
++ \a Key is the type used for lookup keys and \a T is the mapped value
++ type. It stores (key, value) pairs and provides fast lookup by key.
++
++ QMap and QHash provide very similar functionality. The
++ differences are:
++
++ \list
++ \li QHash provides average faster lookups than QMap. (See \l{Algorithmic
++ Complexity} for details.)
++ \li When iterating over a QHash, the items are arbitrarily ordered.
++ With QMap, the items are always sorted by key.
++ \li The key type of a QHash must provide operator==() and a global
++ qHash(Key) function. The key type of a QMap must provide
++ operator<() specifying a total order. Since Qt 5.8.1 it is also safe
++ to use a pointer type as key, even if the underlying operator<()
++ does not provide a total order.
++ \endlist
++
++ Here's an example QMap with QString keys and \c int values:
++ \snippet code/src_corelib_tools_qmap.cpp 0
++
++ To insert a (key, value) pair into the map, you can use operator[]():
++
++ \snippet code/src_corelib_tools_qmap.cpp 1
++
++ This inserts the following three (key, value) pairs into the
++ QMap: ("one", 1), ("three", 3), and ("seven", 7). Another way to
++ insert items into the map is to use insert():
++
++ \snippet code/src_corelib_tools_qmap.cpp 2
++
++ To look up a value, use operator[]() or value():
++
++ \snippet code/src_corelib_tools_qmap.cpp 3
++
++ If there is no item with the specified key in the map, these
++ functions return a \l{default-constructed value}.
++
++ If you want to check whether the map contains a certain key, use
++ contains():
++
++ \snippet code/src_corelib_tools_qmap.cpp 4
++
++ There is also a value() overload that uses its second argument as
++ a default value if there is no item with the specified key:
++
++ \snippet code/src_corelib_tools_qmap.cpp 5
++
++ In general, we recommend that you use contains() and value()
++ rather than operator[]() for looking up a key in a map. The
++ reason is that operator[]() silently inserts an item into the
++ map if no item exists with the same key (unless the map is
++ const). For example, the following code snippet will create 1000
++ items in memory:
++
++ \snippet code/src_corelib_tools_qmap.cpp 6
++
++ To avoid this problem, replace \c map[i] with \c map.value(i)
++ in the code above.
++
++ If you want to navigate through all the (key, value) pairs stored
++ in a QMap, you can use an iterator. QMap provides both
++ \l{Java-style iterators} (QMapIterator and QMutableMapIterator)
++ and \l{STL-style iterators} (QMap::const_iterator and
++ QMap::iterator). Here's how to iterate over a QMap<QString, int>
++ using a Java-style iterator:
++
++ \snippet code/src_corelib_tools_qmap.cpp 7
++
++ Here's the same code, but using an STL-style iterator this time:
++
++ \snippet code/src_corelib_tools_qmap.cpp 8
++
++ The items are traversed in ascending key order.
++
++ A QMap allows only one value per key. If you call
++ insert() with a key that already exists in the QMap, the
++ previous value will be erased. For example:
++
++ \snippet code/src_corelib_tools_qmap.cpp 9
++
++ However, you can store multiple values per key by using
++ QMultiMap.
++
++ If you only need to extract the values from a map (not the keys),
++ you can also use range-based for:
++
++ \snippet code/src_corelib_tools_qmap.cpp 12
++
++ Items can be removed from the map in several ways. One way is to
++ call remove(); this will remove any item with the given key.
++ Another way is to use QMutableMapIterator::remove(). In addition,
++ you can clear the entire map using clear().
++
++ QMap's key and value data types must be \l{assignable data
++ types}. This covers most data types you are likely to encounter,
++ but the compiler won't let you, for example, store a QWidget as a
++ value; instead, store a QWidget *. In addition, QMap's key type
++ must provide operator<(). QMap uses it to keep its items sorted,
++ and assumes that two keys \c x and \c y are equivalent if neither \c{x
++ < y} nor \c{y < x} is true.
++
++ Example:
++ \snippet code/src_corelib_tools_qmap.cpp 13
++
++ In the example, we start by comparing the employees' names. If
++ they're equal, we compare their dates of birth to break the tie.
++
++ \sa QMapIterator, QMutableMapIterator, QHash, QSet
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::QMap()
++
++ Constructs an empty map.
++
++ \sa clear()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::QMap(const QMap<Key, T> &other)
++
++ Constructs a copy of \a other.
++
++ This operation occurs in \l{constant time}, because QMap is
++ \l{implicitly shared}. This makes returning a QMap from a
++ function very fast. If a shared instance is modified, it will be
++ copied (copy-on-write), and this takes \l{linear time}.
++
++ \sa operator=
++ */
++
++ /*!
++ \fn template <class Key, class T> QMap<Key, T>::QMap(QMap<Key, T> &&other)
++
++ Move-constructs a QMap instance.
++
++ \since 5.2
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T> &QMap<Key, T>::operator=(const QMap<Key, T> &other)
++
++ Assigns \a other to this map and returns a reference to this map.
++ */
++
++ /*!
++ \fn template <class Key, class T> QMap<Key, T> &QMap<Key, T>::operator=(QMap<Key, T> &&other)
++
++ Move-assigns \a other to this QMap instance.
++
++ \since 5.2
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::~QMap()
++
++ Destroys the map. References to the values in the map, and all
++ iterators over this map, become invalid.
++ */
++
++ /*! \fn template <class Key, class T> void QMap<Key, T>::swap(QMap<Key, T> &other) noexcept
++ \since 4.8
++ \memberswap{map}
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::QMap(std::initializer_list<std::pair<Key,T> > list)
++ \since 5.1
++
++ Constructs a map with a copy of each of the elements in the
++ initializer list \a list.
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::QMap(const std::map<Key, T> & other)
++
++ Constructs a copy of \a other.
++
++ \sa toStdMap()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::QMap(std::map<Key, T> && other)
++
++ Constructs a map by moving from \a other.
++
++ \sa toStdMap()
++ */
++
++ /*! \fn template <class Key, class T> std::map<Key, T> QMap<Key, T>::toStdMap() const &
++
++ Returns an STL map equivalent to this QMap.
++ */
++
++ /*! \fn template <class Key, class T> std::map<Key, T> QMap<Key, T>::toStdMap() &&
++
++ \overload
++ \since 6.0
++
++ \note Calling this function will leave this QMap in the partially-formed state, in which
++ the only valid operations are destruction or assignment of a new value.
++ */
++
++ /*! \fn template <class Key, class T> bool QMap<Key, T>::operator==(const QMap<Key, T> &lhs, const QMap<Key, T> &rhs)
++
++ Returns \c true if \a lhs is equal to \a rhs; otherwise returns
++ false.
++
++ Two maps are considered equal if they contain the same (key,
++ value) pairs.
++
++ This function requires the key and the value types to implement \c
++ operator==().
++
++ \sa operator!=()
++ */
++
++ /*! \fn template <class Key, class T> bool QMap<Key, T>::operator!=(const QMap<Key, T> &lhs, const QMap<Key, T> &rhs)
++
++ Returns \c true if \a lhs is not equal to \a rhs; otherwise returns
++ false.
++
++ Two maps are considered equal if they contain the same (key,
++ value) pairs.
++
++ This function requires the key and the value types to implement \c
++ operator==().
++
++ \sa operator==()
++ */
++
++ /*! \fn template <class Key, class T> bool QMap<Key, T>::operator<(const QMap<Key, T> &lhs, const QMap<Key, T> &rhs)
++ \since 6.12
++
++ Returns \c true if \a lhs is
++ {lexicographically less than} \a rhs; otherwise returns \c false.
++
++ //! [operator_uses_qt_lex_compare_three_way]
++ This operator is available if both the key type \c Key and the mapped type
++ \c T provide one of \c {operator<=>()} (in C++20 mode),
++ \c {compareThreeWay()} helper method, or \c {operator<()}.
++ //! [operator_uses_qt_lex_compare_three_way]
++ */
++
++ /*! \fn template <class Key, class T> bool QMap<Key, T>::operator>(const QMap<Key, T> &lhs, const QMap<Key, T> &rhs)
++ \since 6.12
++
++ Returns \c true if \a lhs is
++ {lexicographically greater than} \a rhs; otherwise returns \c false.
++
++ \include qmap.qdoc operator_uses_qt_lex_compare_three_way
++ */
++
++ /*! \fn template <class Key, class T> bool QMap<Key, T>::operator<=(const QMap<Key, T> &lhs, const QMap<Key, T> &rhs)
++ \since 6.12
++
++ Returns \c true if \a lhs is
++ {lexicographically less or equal than} \a rhs; otherwise returns \c false.
++
++ \include qmap.qdoc operator_uses_qt_lex_compare_three_way
++ */
++
++ /*! \fn template <class Key, class T> bool QMap<Key, T>::operator>=(const QMap<Key, T> &lhs, const QMap<Key, T> &rhs)
++ \since 6.12
++
++ Returns \c true if \a lhs is
++ {lexicographically greater or equal than} \a rhs; otherwise returns \c false.
++
++ \include qmap.qdoc operator_uses_qt_lex_compare_three_way
++ */
++
++ /*! \fn template <class Key, class T> auto QMap<Key, T>::operator<=>(const QMap<Key, T> &lhs, const QMap<Key, T> &rhs)
++ \since 6.12
++
++ Compares the contents of \a lhs and \a rhs
++ {lexicographically}. Returns the result of the strongest applicable category
++ type.
++
++ //! [operator_in_cpp20_only]
++ \note This operator is only available in C++20 mode when both the key type
++ \c Key and the mapped type \c T meet the requirements of
++ \c {std::three_way_comparable} concept or provide \c {operator<()}.
++ In this case the \c{<}, \c{<=}, \c{>}, and \c{>=} operators are synthesized
++ from \c {operator<=>()} and \c {operator==()}.
++ //! [operator_in_cpp20_only]
++ */
++
++ /*! \fn template <class Key, class T> size_type QMap<Key, T>::size() const
++
++ Returns the number of (key, value) pairs in the map.
++
++ \sa isEmpty(), count()
++ */
++
++ /*!
++ \fn template <class Key, class T> bool QMap<Key, T>::isEmpty() const
++
++ Returns \c true if the map contains no items; otherwise returns
++ false.
++
++ \sa size()
++ */
++
++ /*! \fn template <class Key, class T> void QMap<Key, T>::detach()
++
++ \internal
++
++ Detaches this map from any other maps with which it may share
++ data.
++
++ \sa isDetached()
++ */
++
++ /*! \fn template <class Key, class T> bool QMap<Key, T>::isDetached() const
++
++ \internal
++
++ Returns \c true if the map's internal data isn't shared with any
++ other map object; otherwise returns \c false.
++
++ \sa detach()
++ */
++
++ /*! \fn template <class Key, class T> bool QMap<Key, T>::isSharedWith(const QMap<Key, T> &other) const
++
++ \internal
++ */
++
++ /*! \fn template <class Key, class T> void QMap<Key, T>::clear()
++
++ Removes all items from the map.
++
++ \sa remove()
++ */
++
++ /*! \fn template <class Key, class T> size_type QMap<Key, T>::remove(const Key &key)
++
++ Removes all the items that have the key \a key from the map.
++ Returns the number of items removed which will be 1 if the key
++ exists in the map, and 0 otherwise.
++
++ \sa clear(), take()
++ */
++
++ /*! \fn template <class Key, class T> template <typename Predicate> size_type QMap<Key, T>::removeIf(Predicate pred)
++ \since 6.1
++
++ Removes all elements for which the predicate \a pred returns true
++ from the map.
++
++ The function supports predicates which take either an argument of
++ type \c{QMap<Key, T>::iterator}, or an argument of type
++ \c{std::pair<const Key &, T &>}.
++
++ Returns the number of elements removed, if any.
++
++ \sa clear(), take()
++ */
++
++ /*! \fn template <class Key, class T> T QMap<Key, T>::take(const Key &key)
++
++ Removes the item with the key \a key from the map and returns
++ the value associated with it.
++
++ If the item does not exist in the map, the function simply
++ returns a \l{default-constructed value}.
++
++ If you don't use the return value, remove() is more efficient.
++
++ \sa remove()
++ */
++
++ /*! \fn template <class Key, class T> bool QMap<Key, T>::contains(const Key &key) const
++
++ Returns \c true if the map contains an item with key \a key;
++ otherwise returns \c false.
++
++ \sa count()
++ */
++
++ /*!
++ \fn template <class Key, class T> Key QMap<Key, T>::key(const T &value, const Key &defaultKey) const
++ \since 4.3
++ \overload
++
++ Returns the first key with value \a value, or \a defaultKey if
++ the map contains no item with value \a value. If no \a defaultKey
++ is provided the function returns a
++ \l{default-constructed value}{default-constructed key}.
++
++ This function can be slow (\l{linear time}), because QMap's
++ internal data structure is optimized for fast lookup by key, not
++ by value.
++
++ \sa value(), keys()
++ */
++
++ /*! \fn template <class Key, class T> T QMap<Key, T>::value(const Key &key, const T &defaultValue) const
++
++ Returns the value associated with the key \a key.
++
++ If the map contains no item with key \a key, the function returns
++ \a defaultValue. If no \a defaultValue is specified, the function
++ returns a \l{default-constructed value}.
++
++ \sa key(), values(), contains(), operator[]()
++ */
++
++ /*! \fn template <class Key, class T> T &QMap<Key, T>::operator[](const Key &key)
++
++ Returns the value associated with the key \a key as a modifiable
++ reference.
++
++ If the map contains no item with key \a key, the function inserts
++ a \l{default-constructed value} into the map with key \a key, and
++ returns a reference to it.
++
++ \sa insert(), value()
++ */
++
++ /*! \fn template <class Key, class T> T QMap<Key, T>::operator[](const Key &key) const
++
++ \overload
++
++ Same as value().
++ */
++
++ /*! \fn template <class Key, class T> QList<Key> QMap<Key, T>::keys() const
++
++ Returns a list containing all the keys in the map in ascending
++ order.
++
++ The order is guaranteed to be the same as that used by values().
++
++ This function creates a new list, in \l {linear time}. The time and memory
++ use that entails can be avoided by iterating from \l keyBegin() to
++ \l keyEnd().
++
++ \sa values(), key()
++ */
++
++ /*! \fn template <class Key, class T> QList<Key> QMap<Key, T>::keys(const T &value) const
++
++ \overload
++
++ Returns a list containing all the keys associated with value \a
++ value in ascending order.
++
++ This function can be slow (\l{linear time}), because QMap's
++ internal data structure is optimized for fast lookup by key, not
++ by value.
++ */
++
++ /*! \fn template <class Key, class T> QList<T> QMap<Key, T>::values() const
++
++ Returns a list containing all the values in the map, in ascending
++ order of their keys.
++
++ This function creates a new list, in \l {linear time}. The time and memory
++ use that entails can be avoided by iterating from \l keyValueBegin() to
++ \l keyValueEnd().
++
++ \sa keys(), value()
++ */
++
++ /*! \fn template <class Key, class T> size_type QMap<Key, T>::count(const Key &key) const
++
++ Returns the number of items associated with key \a key.
++
++ \sa contains()
++ */
++
++ /*! \fn template <class Key, class T> size_type QMap<Key, T>::count() const
++
++ \overload
++
++ Same as size().
++ */
++
++ /*! \fn template <class Key, class T> const Key &QMap<Key, T>::firstKey() const
++ \since 5.2
++
++ Returns a reference to the smallest key in the map.
++ This function assumes that the map is not empty.
++
++ This executes in \l{constant time}.
++
++ \sa lastKey(), first(), keyBegin(), isEmpty()
++ */
++
++ /*! \fn template <class Key, class T> const Key &QMap<Key, T>::lastKey() const
++ \since 5.2
++
++ Returns a reference to the largest key in the map.
++ This function assumes that the map is not empty.
++
++ This executes in \l{constant time}.
++
++ \sa firstKey(), last(), keyEnd(), isEmpty()
++ */
++
++ /*! \fn template <class Key, class T> T &QMap<Key, T>::first()
++ \since 5.2
++
++ Returns a reference to the first value in the map, that is the value mapped
++ to the smallest key. This function assumes that the map is not empty.
++
++ When unshared (or const version is called), this executes in \l{constant time}.
++
++ \sa last(), firstKey(), isEmpty()
++ */
++
++ /*! \fn template <class Key, class T> const T &QMap<Key, T>::first() const
++ \since 5.2
++
++ \overload
++ */
++
++ /*! \fn template <class Key, class T> T &QMap<Key, T>::last()
++ \since 5.2
++
++ Returns a reference to the last value in the map, that is the value mapped
++ to the largest key. This function assumes that the map is not empty.
++
++ When unshared (or const version is called), this executes in \l{constant time}.
++
++ \sa first(), lastKey(), isEmpty()
++ */
++
++ /*! \fn template <class Key, class T> const T &QMap<Key, T>::last() const
++ \since 5.2
++
++ \overload
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::begin()
++
++ Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first item in
++ the map.
++
++ \sa constBegin(), end()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::begin() const
++
++ \overload
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::cbegin() const
++ \since 5.0
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
++ in the map.
++
++ \sa begin(), cend()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::constBegin() const
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
++ in the map.
++
++ \sa begin(), constEnd()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::key_iterator QMap<Key, T>::keyBegin() const
++ \since 5.6
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first key
++ in the map.
++
++ \sa keyEnd(), firstKey()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::end()
++
++ Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary item
++ after the last item in the map.
++
++ \sa begin(), constEnd()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::end() const
++
++ \overload
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::cend() const
++ \since 5.0
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
++ item after the last item in the map.
++
++ \sa cbegin(), end()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::constEnd() const
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
++ item after the last item in the map.
++
++ \sa constBegin(), end()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::key_iterator QMap<Key, T>::keyEnd() const
++ \since 5.6
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
++ item after the last key in the map.
++
++ \sa keyBegin(), lastKey()
++ */
++
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::key_value_iterator QMap<Key, T>::keyValueBegin()
++ \since 5.10
++
++ Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first entry
++ in the map.
++
++ \sa keyValueEnd()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::key_value_iterator QMap<Key, T>::keyValueEnd()
++ \since 5.10
++
++ Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
++ entry after the last entry in the map.
++
++ \sa keyValueBegin()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_key_value_iterator QMap<Key, T>::keyValueBegin() const
++ \since 5.10
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
++ in the map.
++
++ \sa keyValueEnd()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_key_value_iterator QMap<Key, T>::constKeyValueBegin() const
++ \since 5.10
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
++ in the map.
++
++ \sa keyValueBegin()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_key_value_iterator QMap<Key, T>::keyValueEnd() const
++ \since 5.10
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
++ entry after the last entry in the map.
++
++ \sa keyValueBegin()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_key_value_iterator QMap<Key, T>::constKeyValueEnd() const
++ \since 5.10
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
++ entry after the last entry in the map.
++
++ \sa constKeyValueBegin()
++ */
++
++ /*! \fn template <class Key, class T> auto QMap<Key, T>::asKeyValueRange() &
++ \fn template <class Key, class T> auto QMap<Key, T>::asKeyValueRange() const &
++ \fn template <class Key, class T> auto QMap<Key, T>::asKeyValueRange() &&
++ \fn template <class Key, class T> auto QMap<Key, T>::asKeyValueRange() const &&
++ \since 6.4
++
++ Returns a range object that allows iteration over this map as
++ key/value pairs. For instance, this range object can be used in a
++ range-based for loop, in combination with a structured binding declaration:
++
++ \snippet code/src_corelib_tools_qmap.cpp 28
++
++ Note that both the key and the value obtained this way are
++ references to the ones in the map. Specifically, mutating the value
++ will modify the map itself.
++
++ \sa QKeyValueIterator
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::erase(const_iterator pos)
++
++ Removes the (key, value) pair pointed to by the iterator \a pos
++ from the map, and returns an iterator to the next item in the
++ map.
++
++ \note The iterator \a pos \e must be valid and dereferenceable.
++
++ \sa remove()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::erase(const_iterator first, const_iterator last)
++ \since 6.0
++
++ Removes the (key, value) pairs pointed to by the iterator range
++ [\a first, \a last) from the map.
++ Returns an iterator to the item in the map following the last removed element.
++
++ \note The range \c {[first, last)} \e must be a valid range in \c {*this}.
++
++ \sa remove()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::find(const Key &key)
++
++ Returns an iterator pointing to the item with key \a key in the
++ map.
++
++ If the map contains no item with key \a key, the function
++ returns end().
++
++ \sa constFind(), value(), values(), lowerBound(), upperBound()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::find(const Key &key) const
++
++ \overload
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::constFind(const Key &key) const
++ \since 4.1
++
++ Returns an const iterator pointing to the item with key \a key in the
++ map.
++
++ If the map contains no item with key \a key, the function
++ returns constEnd().
++
++ \sa find()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::lowerBound(const Key &key)
++
++ Returns an iterator pointing to the first item with key \a key in
++ the map. If the map contains no item with key \a key, the
++ function returns an iterator to the nearest item with a greater
++ key.
++
++ \sa upperBound(), find()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::lowerBound(const Key &key) const
++
++ \overload
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::upperBound(const Key &key)
++
++ Returns an iterator pointing to the item that immediately follows
++ the last item with key \a key in the map. If the map contains no
++ item with key \a key, the function returns an iterator to the
++ nearest item with a greater key.
++
++ Example:
++ \snippet code/src_corelib_tools_qmap.cpp 17
++
++ \sa lowerBound(), find()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::upperBound(const Key &key) const
++
++ \overload
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::insert(const Key &key, const T &value)
++
++ Inserts a new item with the key \a key and a value of \a value.
++
++ If there is already an item with the key \a key, that item's value
++ is replaced with \a value.
++
++ Inserting a key/value pair with an existing key replaces the existing
++ value.
++
++ Returns an iterator pointing to the new/updated element.
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::insert(const_iterator pos, const Key &key, const T &value)
++ \overload
++ \since 5.1
++ Inserts a new item with the key \a key and value \a value and with hint \a pos
++ suggesting where to do the insert.
++
++ If constBegin() is used as hint it indicates that the \a key is less than any key in the map
++ while constEnd() suggests that the \a key is (strictly) larger than any key in the map.
++ Otherwise the hint should meet the condition (\a pos - 1).key() < \a key <= pos.key().
++ If the hint \a pos is wrong it is ignored and a regular insert is done.
++
++ If there is already an item with the key \a key, that item's value
++ is replaced with \a value.
++
++ If the hint is correct and the map is unshared, the insert executes in amortized \l{constant time}.
++
++ When creating a map from sorted data inserting the largest key first with constBegin()
++ is faster than inserting in sorted order with constEnd(), since constEnd() - 1 (which is needed
++ to check if the hint is valid) needs \l{logarithmic time}.
++
++ \b {Note:} Be careful with the hint. Providing an iterator from an older shared instance might
++ crash but there is also a risk that it will silently corrupt both the map and the \a pos map.
++
++ Returns an iterator pointing to the new/updated element.
++ */
++
++ /*! \fn template <class Key, class T> void QMap<Key, T>::insert(const QMap<Key, T> &map)
++ \since 5.15
++
++ Inserts all the items in \a map into this map.
++
++ If a key is common to both maps, its value will be replaced with
++ the value stored in \a map.
++ */
++
++ /*! \fn template <class Key, class T> void QMap<Key, T>::insert(QMap<Key, T> &&map)
++ \since 5.15
++
++ Moves all the items from \a map into this map.
++
++ If a key is common to both maps, its value will be replaced with
++ the value stored in \a map.
++
++ If \a map is shared, then the items will be copied instead.
++ */
++
++ /*! \typedef QMap::Iterator
++
++ Qt-style synonym for QMap::iterator.
++ */
++
++ /*! \typedef QMap::ConstIterator
++
++ Qt-style synonym for QMap::const_iterator.
++ */
++
++ /*! \typedef QMap::difference_type
++
++ Typedef for ptrdiff_t. Provided for STL compatibility.
++ */
++
++ /*! \typedef QMap::key_type
++
++ Typedef for Key. Provided for STL compatibility.
++ */
++
++ /*! \typedef QMap::mapped_type
++
++ Typedef for T. Provided for STL compatibility.
++ */
++
++ /*! \typedef QMap::size_type
++
++ Typedef for int. Provided for STL compatibility.
++ */
++
++ /*!
++ \fn template <class Key, class T> bool QMap<Key, T>::empty() const
++
++ This function is provided for STL compatibility. It is equivalent
++ to isEmpty(), returning true if the map is empty; otherwise
++ returning false.
++ */
++
++ /*!
++ \fn template <class Key, class T> std::pair<typename QMap<Key, T>::iterator, typename QMap<Key, T>::iterator> QMap<Key, T>::equal_range(const Key &key)
++
++ Returns a pair of iterators delimiting the range of values \c{[first, second)}, that
++ are stored under \a key.
++ */
++
++ /*!
++ \fn template <class Key, class T> std::pair<typename QMap<Key, T>::const_iterator, typename QMap<Key, T>::const_iterator> QMap<Key, T>::equal_range(const Key &key) const
++ \overload
++ \since 5.6
++ */
++
++
++ /*! \class QMap::iterator
++ \inmodule QtCore
++ \brief The QMap::iterator class provides an STL-style non-const iterator for QMap.
++
++ QMap\<Key, T\>::iterator allows you to iterate over a QMap
++ and to modify the value (but not the key) stored under
++ a particular key. If you want to iterate over a const QMap, you
++ should use QMap::const_iterator. It is generally good practice to
++ use QMap::const_iterator on a non-const QMap as well, unless you
++ need to change the QMap through the iterator. Const iterators are
++ slightly faster, and can improve code readability.
++
++ The default QMap::iterator constructor creates an uninitialized
++ iterator. You must initialize it using a QMap function like
++ QMap::begin(), QMap::end(), or QMap::find() before you can
++ start iterating. Here's a typical loop that prints all the (key,
++ value) pairs stored in a map:
++
++ \snippet code/src_corelib_tools_qmap.cpp 18
++
++ Unlike QHash, which stores its items in an arbitrary order, QMap
++ stores its items ordered by key.
++
++ Here's an example that increments every value stored in the QMap
++ by 2:
++
++ \snippet code/src_corelib_tools_qmap.cpp 19
++
++ To remove elements from a QMap you can use erase_if(QMap\<Key, T\> &map, Predicate pred):
++
++ \snippet code/src_corelib_tools_qmap.cpp 21
++
++ Multiple iterators can be used on the same map. If you add items
++ to the map, existing iterators will remain valid. If you remove
++ items from the map, iterators that point to the removed items
++ will become dangling iterators.
++
++ \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 QMap::const_iterator, QMap::key_iterator, QMap::key_value_iterator
++ */
++
++ /*! \typedef QMap::iterator::difference_type
++
++ \internal
++ */
++
++ /*! \typedef QMap::iterator::iterator_category
++
++ A synonym for \e {std::bidirectional_iterator_tag} indicating
++ this iterator is a bidirectional iterator.
++ */
++
++ /*! \typedef QMap::iterator::pointer
++
++ \internal
++ */
++
++ /*! \typedef QMap::iterator::reference
++
++ \internal
++ */
++
++ /*! \typedef QMap::iterator::value_type
++
++ \internal
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::iterator::iterator()
++
++ Constructs an uninitialized iterator.
++
++ Functions like key(), value(), and operator++() must not be
++ called on an uninitialized iterator. Use operator=() to assign a
++ value to it before using it.
++
++ \sa QMap::begin(), QMap::end()
++ */
++
++ /*! \fn template <class Key, class T> const Key &QMap<Key, T>::iterator::key() const
++
++ Returns the current item's key as a const reference.
++
++ There is no direct way of changing an item's key through an
++ iterator, although it can be done by calling QMap::erase()
++ followed by QMap::insert().
++
++ \sa value()
++ */
++
++ /*! \fn template <class Key, class T> T &QMap<Key, T>::iterator::value() const
++
++ Returns a modifiable reference to the current item's value.
++
++ You can change the value of an item by using value() on
++ the left side of an assignment, for example:
++
++ \snippet code/src_corelib_tools_qmap.cpp 23
++
++ \sa key(), operator*()
++ */
++
++ /*! \fn template <class Key, class T> T &QMap<Key, T>::iterator::operator*() const
++
++ Returns a modifiable reference to the current item's value.
++
++ Same as value().
++
++ \sa key()
++ */
++
++ /*! \fn template <class Key, class T> T *QMap<Key, T>::iterator::operator->() const
++
++ Returns a pointer to the current item's value.
++
++ \sa value()
++ */
++
++ /*!
++ \fn template <class Key, class T> bool QMap<Key, T>::iterator::operator==(const iterator &lhs, const iterator &rhs)
++ \fn template <class Key, class T> bool QMap<Key, T>::const_iterator::operator==(const const_iterator &lhs, const const_iterator &rhs)
++
++ Returns \c true if \a lhs points to the same item as the \a rhs iterator;
++ otherwise returns \c false.
++
++ \sa operator!=()
++ */
++
++ /*!
++ \fn template <class Key, class T> bool QMap<Key, T>::iterator::operator!=(const iterator &lhs, const iterator &rhs)
++ \fn template <class Key, class T> bool QMap<Key, T>::const_iterator::operator!=(const const_iterator &lhs, const const_iterator &rhs)
++
++ Returns \c true if \a lhs points to a different item than the \a rhs iterator;
++ otherwise returns \c false.
++
++ \sa operator==()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::iterator &QMap<Key, T>::iterator::operator++()
++
++ The prefix \c{++} operator (\c{++i}) advances the iterator to the
++ next item in the map and returns an iterator to the new current
++ item.
++
++ Calling this function on QMap::end() leads to undefined results.
++
++ \sa operator--()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator++(int)
++
++ \overload
++
++ The postfix \c{++} operator (\c{i++}) advances the iterator to the
++ next item in the map and returns an iterator to the previously
++ current item.
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::iterator &QMap<Key, T>::iterator::operator--()
++
++ The prefix \c{--} operator (\c{--i}) makes the preceding item
++ current and returns an iterator pointing to the new current item.
++
++ Calling this function on QMap::begin() leads to undefined
++ results.
++
++ \sa operator++()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator--(int)
++
++ \overload
++
++ The postfix \c{--} operator (\c{i--}) makes the preceding item
++ current and returns an iterator pointing to the previously
++ current item.
++ */
++
++ /*! //! friends
++ \fn [qmap-op-it-plus-step] template <class Key, class T> typename QMap<Key, T>::iterator QMap<Key, T>::iterator::operator+(QMap<Key, T>::iterator, difference_type n)
++ \fn [qmap-op-step-plus-it] template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator+(difference_type n, QMap<Key, T>::iterator)
++ \fn [qmap-op-it-minus-step] template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator-(QMap<Key, T>::iterator, difference_type n)
++ \fn [qmap-op-step-minus-it] template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator-(difference_type n, QMap<Key, T>::iterator)
++
++ //! members
++ \fn template <class Key, class T> typename QMap<Key, T>::iterator QMap<Key, T>::iterator::operator+=(QMap<Key, T>::iterator::difference_type n)
++ \fn template <class Key, class T> typename QMap<Key, T>::iterator QMap<Key, T>::iterator::operator-=(QMap<Key, T>::iterator::difference_type n)
++
++ \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
++
++ Moves an iterator by \e{n} positions. These operations can be
++ expensive for large values of \e{n}; QMap iterators are not
++ random access.
++ */
++
++ /*! \class QMap::const_iterator
++ \inmodule QtCore
++ \brief The QMap::const_iterator class provides an STL-style const iterator for QMap.
++
++ QMap\<Key, T\>::const_iterator allows you to iterate over a QMap.
++ If you want to modify the QMap as you iterate
++ over it, you must use QMap::iterator instead. It is generally
++ good practice to use QMap::const_iterator on a non-const QMap as
++ well, unless you need to change the QMap through the iterator.
++ Const iterators are slightly faster, and can improve code
++ readability.
++
++ The default QMap::const_iterator constructor creates an
++ uninitialized iterator. You must initialize it using a QMap
++ function like QMap::cbegin(), QMap::cend(), or
++ QMap::constFind() before you can start iterating. Here's a typical
++ loop that prints all the (key, value) pairs stored in a map:
++
++ \snippet code/src_corelib_tools_qmap.cpp 24
++
++ Here's an example that removes all the items whose value is greater than 10:
++
++ \snippet code/src_corelib_tools_qmap.cpp 20
++
++ And here the same behavior with erase_if()
++
++ \snippet code/src_corelib_tools_qmap.cpp 21
++
++ Unlike QHash, which stores its items in an arbitrary order, QMap
++ stores its items ordered by key.
++
++ Multiple iterators can be used on the same map. If you add items
++ to the map, existing iterators will remain valid. If you remove
++ items from the map, iterators that point to the removed items
++ will become dangling iterators.
++
++ \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 QMap::iterator, QMap::key_iterator, QMap::const_key_value_iterator
++ */
++
++ /*! \typedef QMap::const_iterator::difference_type
++
++ \internal
++ */
++
++ /*! \typedef QMap::const_iterator::iterator_category
++
++ A synonym for \e {std::bidirectional_iterator_tag} indicating
++ this iterator is a bidirectional iterator.
++ */
++
++ /*! \typedef QMap::const_iterator::pointer
++
++ \internal
++ */
++
++ /*! \typedef QMap::const_iterator::reference
++
++ \internal
++ */
++
++ /*! \typedef QMap::const_iterator::value_type
++
++ \internal
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator::const_iterator()
++
++ Constructs an uninitialized iterator.
++
++ Functions like key(), value(), and operator++() must not be
++ called on an uninitialized iterator. Use operator=() to assign a
++ value to it before using it.
++
++ \sa QMap::constBegin(), QMap::constEnd()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator::const_iterator(const iterator &other)
++
++ Constructs a copy of \a other.
++ */
++
++ /*! \fn template <class Key, class T> const Key &QMap<Key, T>::const_iterator::key() const
++
++ Returns the current item's key.
++
++ \sa value()
++ */
++
++ /*! \fn template <class Key, class T> const T &QMap<Key, T>::const_iterator::value() const
++
++ Returns the current item's value.
++
++ \sa key(), operator*()
++ */
++
++ /*! \fn template <class Key, class T> const T &QMap<Key, T>::const_iterator::operator*() const
++
++ Returns the current item's value.
++
++ Same as value().
++
++ \sa key()
++ */
++
++ /*! \fn template <class Key, class T> const T *QMap<Key, T>::const_iterator::operator->() const
++
++ Returns a pointer to the current item's value.
++
++ \sa value()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator &QMap<Key, T>::const_iterator::operator++()
++
++ The prefix \c{++} operator (\c{++i}) advances the iterator to the
++ next item in the map and returns an iterator to the new current
++ item.
++
++ Calling this function on QMap::end() leads to undefined results.
++
++ \sa operator--()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator++(int)
++
++ \overload
++
++ The postfix \c{++} operator (\c{i++}) advances the iterator to the
++ next item in the map and returns an iterator to the previously
++ current item.
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator &QMap<Key, T>::const_iterator::operator--()
++
++ The prefix \c{--} operator (\c{--i}) makes the preceding item
++ current and returns an iterator pointing to the new current item.
++
++ Calling this function on QMap::begin() leads to undefined
++ results.
++
++ \sa operator++()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator--(int)
++
++ \overload
++
++ The postfix \c{--} operator (\c{i--}) makes the preceding item
++ current and returns an iterator pointing to the previously
++ current item.
++ */
++
++ /*! //! friends
++ \fn [qmap-op-it-plus-step-const] template <class Key, class T> QMap<Key, T>::const_iterator::operator+(QMap<Key, T>::const_iterator, difference_type n)
++ \fn [qmap-op-step-plus-it-const] template <class Key, class T> QMap<Key, T>::operator+(difference_type n, QMap<Key, T>::const_iterator)
++ \fn [qmap-op-it-minus-step-const] template <class Key, class T> QMap<Key, T>::operator-(QMap<Key, T>::const_iterator, difference_type n)
++ \fn [qmap-op-step-minus-it-const] template <class Key, class T> QMap<Key, T>::operator-(difference_type n, QMap<Key, T>::const_iterator)
++
++ //! members
++ \fn template <class Key, class T> typename QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator+=(QMap<Key, T>::const_iterator::difference_type n)
++ \fn template <class Key, class T> typename QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator-=(QMap<Key, T>::const_iterator::difference_type n)
++
++ \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
++
++ Moves an iterator by \e{n} positions. These operations can be
++ expensive for large values of \e{n}. QMap iterators are not
++ random access.
++ */
++
++ /*! \class QMap::key_iterator
++ \inmodule QtCore
++ \since 5.6
++ \brief The QMap::key_iterator class provides an STL-style const iterator for QMap keys.
++
++ QMap::key_iterator is essentially the same as QMap::const_iterator
++ with the difference that operator*() and operator->() return a key
++ instead of a value.
++
++ For most uses QMap::iterator and QMap::const_iterator should be used,
++ you can easily access the key by calling QMap::iterator::key():
++
++ \snippet code/src_corelib_tools_qmap.cpp keyiterator1
++
++ However, to have interoperability between QMap's keys and STL-style
++ algorithms we need an iterator that dereferences to a key instead
++ of a value. With QMap::key_iterator we can apply an algorithm to a
++ range of keys without having to call QMap::keys(), which is inefficient
++ as it costs one QMap iteration and memory allocation to create a temporary
++ QList.
++
++ \snippet code/src_corelib_tools_qmap.cpp keyiterator2
++
++ QMap::key_iterator is const, it's not possible to modify the key.
++
++ The default QMap::key_iterator constructor creates an uninitialized
++ iterator. You must initialize it using a QMap function like
++ QMap::keyBegin() or QMap::keyEnd().
++
++ \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 QMap::const_iterator, QMap::iterator
++ */
++
++ /*! \typedef QMap::key_iterator::difference_type
++ \internal
++ */
++
++ /*! \typedef QMap::key_iterator::iterator_category
++ \internal
++ */
++
++ /*! \typedef QMap::key_iterator::pointer
++ \internal
++ */
++
++ /*! \typedef QMap::key_iterator::reference
++ \internal
++ */
++
++ /*! \typedef QMap::key_iterator::value_type
++ \internal
++ */
++
++ /*! \fn template <class Key, class T> const T &QMap<Key, T>::key_iterator::operator*() const
++
++ Returns the current item's key.
++ */
++
++ /*! \fn template <class Key, class T> const T *QMap<Key, T>::key_iterator::operator->() const
++
++ Returns a pointer to the current item's key.
++ */
++
++ /*! \fn template <class Key, class T> bool QMap<Key, T>::key_iterator::operator==(key_iterator other) const
++
++ Returns \c true if \a other points to the same item as this
++ iterator; otherwise returns \c false.
++
++ \sa operator!=()
++ */
++
++ /*! \fn template <class Key, class T> bool QMap<Key, T>::key_iterator::operator!=(key_iterator other) const
++
++ Returns \c true if \a other points to a different item than this
++ iterator; otherwise returns \c false.
++
++ \sa operator==()
++ */
++
++ /*!
++ \fn template <class Key, class T> QMap<Key, T>::key_iterator &QMap<Key, T>::key_iterator::operator++()
++
++ The prefix \c{++} operator (\c{++i}) advances the iterator to the
++ next item in the hash and returns an iterator to the new current
++ item.
++
++ Calling this function on QMap::keyEnd() leads to undefined results.
++
++ \sa operator--()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::key_iterator QMap<Key, T>::key_iterator::operator++(int)
++
++ \overload
++
++ The postfix \c{++} operator (\c{i++}) advances the iterator to the
++ next item in the hash and returns an iterator to the previous
++ item.
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::key_iterator &QMap<Key, T>::key_iterator::operator--()
++
++ The prefix \c{--} operator (\c{--i}) makes the preceding item
++ current and returns an iterator pointing to the new current item.
++
++ Calling this function on QMap::keyBegin() leads to undefined
++ results.
++
++ \sa operator++()
++ */
++
++ /*! \fn template <class Key, class T> QMap<Key, T>::key_iterator QMap<Key, T>::key_iterator::operator--(int)
++
++ \overload
++
++ The postfix \c{--} operator (\c{i--}) makes the preceding item
++ current and returns an iterator pointing to the previous
++ item.
++ */
++
++ /*! \fn template <class Key, class T> const_iterator QMap<Key, T>::key_iterator::base() const
++ Returns the underlying const_iterator this key_iterator is based on.
++ */
++
++ /*! \typedef QMap::const_key_value_iterator
++ \inmodule QtCore
++ \since 5.10
++ \brief The QMap::const_key_value_iterator typedef provides an STL-style iterator for QMap.
++
++ QMap::const_key_value_iterator is essentially the same as QMap::const_iterator
++ with the difference that operator*() returns a key/value pair instead of a
++ value.
++
++ \sa QKeyValueIterator
++ */
++
++ /*! \typedef QMap::key_value_iterator
++ \inmodule QtCore
++ \since 5.10
++ \brief The QMap::key_value_iterator typedef provides an STL-style iterator for QMap.
++
++ QMap::key_value_iterator is essentially the same as QMap::iterator
++ with the difference that operator*() returns a key/value pair instead of a
++ value.
++
++ \sa QKeyValueIterator
++ */
++
++ /*! \fn template <class Key, class T> QDataStream &operator<<(QDataStream &out, const QMap<Key, T> &map)
++ \relates QMap
++
++ Writes the map \a map to stream \a out.
++
++ This function requires the key and value types to implement \c
++ operator<<().
++
++ \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
++ */
++
++ /*! \fn template <class Key, class T> QDataStream &operator>>(QDataStream &in, QMap<Key, T> &map)
++ \relates QMap
++
++ Reads a map from stream \a in into \a map.
++
++ This function requires the key and value types to implement \c
++ operator>>().
++
++ \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
++ */
++
++ /*! \fn template <typename Key, typename T, typename Predicate> qsizetype erase_if(QMap<Key, T> &map, Predicate pred)
++ \relates QMap
++ \since 6.1
++
++ Removes all elements for which the predicate \a pred returns true
++ from the map \a map.
++
++ The function supports predicates which take either an argument of
++ type \c{QMap<Key, T>::iterator}, or an argument of type
++ \c{std::pair<const Key &, T &>}.
++
++ Returns the number of elements removed, if any.
++ */
++
++ /*!
++ \fn template <class Key, class T> size_t QMap<Key, T>::qHash(const QMap &key, size_t seed) noexcept
++ \since 6.8
++ \qhashTS{QMap}{Key}{T}
++ */