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) 2020 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \class QMultiMap
++ \inmodule QtCore
++ \brief The QMultiMap class is a template class that provides an associative array with multiple equivalent keys.
++ \compares equality
++
++ \ingroup tools
++ \ingroup shared
++ \ingroup containers
++
++ \reentrant
++
++ QMultiMap\<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.
++
++ QMultiMap and QMultiHash provide very similar functionality. The
++ differences are:
++
++ \list
++ \li QMultiHash provides average faster lookups than QMultiMap. (See \l{Algorithmic
++ Complexity} for details.)
++ \li When iterating over a QMultiHash, the items are arbitrarily ordered.
++ With QMultiMap, the items are always sorted by key.
++ \li The key type of a QMultiHash must provide operator==() and a global
++ qHash(Key) function. The key type of a QMultiMap 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 QMultiMap with QString keys and \c int values:
++ \snippet code/src_corelib_tools_qmultimap.cpp 0
++
++ To insert a (key, value) pair into the multi map, you can use insert():
++
++ \snippet code/src_corelib_tools_qmultimap.cpp 2
++
++ This inserts the following four (key, value) pairs into the
++ QMultiMap: ("a", 1), ("b", 3), ("c", 7), and ("c", -5); note
++ that duplicate keys are allowed.
++
++ To look up a value, use find() or value():
++
++ \snippet code/src_corelib_tools_qmultimap.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_qmultimap.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_qmultimap.cpp 5
++
++ If you want to navigate through all the (key, value) pairs stored
++ in a QMultiMap, you can use an iterator. QMultiMap provides both
++ \l{Java-style iterators} (QMultiMapIterator and QMutableMultiMapIterator)
++ and \l{STL-style iterators} (QMultiMap::const_iterator and
++ QMultiMap::iterator). Here's how to iterate over a QMultiMap<QString, int>
++ using a Java-style iterator:
++
++ \snippet code/src_corelib_tools_qmultimap.cpp 7
++
++ Here's the same code, but using an STL-style iterator this time:
++
++ \snippet code/src_corelib_tools_qmultimap.cpp 8
++
++ The items are traversed in ascending key order.
++
++ A QMultiMap allows multiple values per key. If you call
++ insert() with a key that already exists in the map, a
++ new (key, value) pair will be inserted. For example:
++
++ \snippet code/src_corelib_tools_qmultimap.cpp 9
++
++ If you want to retrieve all the values for a single key, you can
++ use values(const Key &key), which returns a QList<T>:
++
++ \snippet code/src_corelib_tools_qmultimap.cpp 10
++
++ The items that share the same key are available from most
++ recently to least recently inserted. Another approach is to call
++ find() to get the STL-style iterator for the first item with a
++ key and iterate from there:
++
++ \snippet code/src_corelib_tools_qmultimap.cpp 11
++ \snippet code/src_corelib_tools_qmultimap.cpp 11_better
++
++ 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_qmultimap.cpp 12
++
++ Items can be removed from the multi map in several ways. One way is to
++ call remove(); this will remove any item with the given key.
++ Another way is to use QMutableMultiMapIterator::remove(). In addition,
++ you can clear the entire map using clear().
++
++ It is possible to merge two multi maps by calling unite(), by
++ using operator+(), and by using operator+=(). Example:
++
++ \snippet code/src_corelib_tools_qmultimap.cpp 25
++
++ QMultiMap'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, QMultiMap'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 equal if neither \c{x
++ < y} nor \c{y < x} is true.
++
++ Example:
++ \snippet code/src_corelib_tools_qmultimap.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 QMultiMapIterator, QMutableMultiMapIterator, QMultiHash
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap()
++
++ Constructs an empty multi map.
++
++ \sa clear()
++ */
++
++ /*!
++ \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap(QMultiMap<Key, T> &&other)
++
++ Move-constructs a QMultiMap instance, making it point at the same
++ object that \a other was pointing to.
++
++ \since 5.2
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap(const QMultiMap<Key, T> &other)
++
++ Constructs a copy of \a other.
++
++ This operation occurs in \l{constant time}, because QMultiMap is
++ \l{implicitly shared}. This makes returning a QMultiMap 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> QMultiMap<Key, T> &QMultiMap<Key, T>::operator=(const QMultiMap<Key, T> &other)
++
++ Assigns \a other to this multi map and returns a reference to this multi map.
++ */
++
++ /*!
++ \fn template <class Key, class T> QMultiMap<Key, T> &QMultiMap<Key, T>::operator=(QMultiMap<Key, T> &&other)
++
++ Move-assigns \a other to this QMultiMap instance.
++
++ \since 5.2
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::~QMultiMap()
++
++ Destroys the multi map. References to the values in the multi map, and all
++ iterators over this multi map, become invalid.
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap(std::initializer_list<std::pair<Key,T> > list)
++ \since 5.1
++
++ Constructs a multi map with a copy of each of the elements in the
++ initializer list \a list.
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap(const QMap<Key, T> &other)
++ \since 6.0
++
++ Constructs a multi map as a copy of \a other.
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap(QMap<Key, T> &&other)
++ \since 6.0
++
++ If \a other is shared, constructs a multi map as a copy of \a other.
++ Otherwise, constructs a multi map by moving the elements from \a other.
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap(const std::multimap<Key, T> &other)
++
++ Constructs a copy of \a other.
++
++ \sa toStdMultiMap()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap(std::multimap<Key, T> &&other)
++
++ Constructs a multi map by moving from \a other.
++
++ \sa toStdMultiMap()
++ */
++
++ /*! \fn template <class Key, class T> std::multimap<Key, T> QMultiMap<Key, T>::toStdMap() const
++ \deprecated [6.0] Use toStdMultiMap() instead.
++
++ Returns an STL multi map equivalent to this QMultiMap.
++ */
++
++ /*! \fn template <class Key, class T> std::multimap<Key, T> QMultiMap<Key, T>::toStdMultiMap() const &
++
++ Returns an STL multi map equivalent to this QMultiMap.
++ */
++
++ /*! \fn template <class Key, class T> void QMultiMap<Key, T>::swap(QMultiMap<Key, T> &other)
++ \since 4.8
++ \memberswap{multi map}
++ */
++
++ /*! \fn template<class Key, class T> bool QMultiMap<Key, T>::operator==(const QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
++
++ Returns \c true if \a lhs is equal to \a rhs; otherwise returns
++ false.
++
++ Two multi maps are considered equal if they contain the same (key,
++ value) pairs, in the same order (which matters for duplicate keys).
++
++ This function requires the key and the value types to implement \c
++ operator==().
++
++ \sa operator!=()
++ */
++
++ /*! \fn template<class Key, class T> bool QMultiMap<Key, T>::operator!=(const QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
++
++ Returns \c true if \a lhs is not equal to \a rhs; otherwise
++ returns \c false.
++
++ Two multi maps are considered equal if they contain the same (key,
++ value) pairs, in the same order (which matters for duplicate keys).
++
++ This function requires the key and the value types to implement \c
++ operator==().
++
++ \sa operator==()
++ */
++
++ /*! \fn template <class Key, class T> bool QMultiMap<Key, T>::operator<(const QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
++ \since 6.12
++
++ Returns \c true if \a lhs is
++ {lexicographically less than} \a rhs; otherwise returns \c false.
++
++ \include qmap.qdoc operator_uses_qt_lex_compare_three_way
++ */
++
++ /*! \fn template <class Key, class T> bool QMultiMap<Key, T>::operator>(const QMultiMap<Key, T> &lhs, const QMultiMap<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 QMultiMap<Key, T>::operator<=(const QMultiMap<Key, T> &lhs, const QMultiMap<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 QMultiMap<Key, T>::operator>=(const QMultiMap<Key, T> &lhs, const QMultiMap<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 QMultiMap<Key, T>::operator<=>(const QMultiMap<Key, T> &lhs, const QMultiMap<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.
++
++ \include qmap.qdoc operator_in_cpp20_only
++ */
++
++ /*! \fn template <class Key, class T> qsizetype QMultiMap<Key, T>::size() const
++
++ Returns the number of (key, value) pairs in the multi map.
++
++ \sa isEmpty(), count()
++ */
++
++ /*!
++ \fn template <class Key, class T> bool QMultiMap<Key, T>::isEmpty() const
++
++ Returns \c true if the multi map contains no items; otherwise returns
++ false.
++
++ \sa size()
++ */
++
++ /*! \fn template <class Key, class T> void QMultiMap<Key, T>::detach()
++
++ \internal
++
++ Detaches this map from any other multi maps with which it may share
++ data.
++
++ \sa isDetached()
++ */
++
++ /*! \fn template <class Key, class T> bool QMultiMap<Key, T>::isDetached() const
++
++ \internal
++
++ Returns \c true if the multi 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 QMultiMap<Key, T>::isSharedWith(const QMultiMap<Key, T> &other) const
++
++ \internal
++ */
++
++ /*! \fn template <class Key, class T> void QMultiMap<Key, T>::clear()
++
++ Removes all items from the multi map.
++
++ \sa remove()
++ */
++
++ /*! \fn template <class Key, class T> qsizetype QMultiMap<Key, T>::remove(const Key &key)
++
++ Removes all the items that have the key \a key from the multi map.
++ Returns the number of items removed.
++
++ \sa clear(), take()
++ */
++
++ /*! \fn template <class Key, class T> qsizetype QMultiMap<Key, T>::remove(const Key &key, const T &value)
++
++ Removes all the items that have the key \a key and value \a value
++ from the multi map.
++ Returns the number of items removed.
++
++ \sa clear(), take()
++ */
++
++ /*! \fn template <class Key, class T> template <typename Predicate> size_type QMultiMap<Key, T>::removeIf(Predicate pred)
++ \since 6.1
++
++ Removes all elements for which the predicate \a pred returns true
++ from the multi map.
++
++ The function supports predicates which take either an argument of
++ type \c{QMultiMap<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 QMultiMap<Key, T>::take(const Key &key)
++
++ Removes the item with the key \a key from the multi map and returns
++ the value associated with it.
++
++ If the item does not exist in the multi map, the function simply
++ returns a \l{default-constructed value}. If there are multiple
++ items for \a key in the map, only the most recently inserted one
++ is removed and returned.
++
++ If you don't use the return value, remove() is more efficient.
++
++ \sa remove()
++ */
++
++ /*! \fn template <class Key, class T> bool QMultiMap<Key, T>::contains(const Key &key) const
++
++ Returns \c true if the multi map contains an item with key \a key;
++ otherwise returns \c false.
++
++ \sa count()
++ */
++
++ /*! \fn template <class Key, class T> bool QMultiMap<Key, T>::contains(const Key &key, const T &value) const
++ \since 4.3
++
++ Returns \c true if the multi map contains an item with key \a key
++ and value \a value; otherwise returns \c false.
++
++ \sa count()
++ */
++
++ /*!
++ \fn template <class Key, class T> Key QMultiMap<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 multi 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 QMultiMap's
++ internal data structure is optimized for fast lookup by key, not
++ by value.
++
++ \sa value(), keys()
++ */
++
++ /*! \fn template <class Key, class T> T QMultiMap<Key, T>::value(const Key &key, const T &defaultValue) const
++
++ Returns the value associated with the key \a key.
++
++ If the multi 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}. If there are multiple
++ items for \a key in the multi map, the value of the most recently
++ inserted one is returned.
++
++ \sa key(), values(), contains()
++ */
++
++ /*! \fn template <class Key, class T> QList<Key> QMultiMap<Key, T>::keys() const
++
++ Returns a list containing all the keys in the multi map in ascending
++ order. Keys that occur multiple times in the multi map
++ also occur multiple times in the list.
++
++ 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> QMultiMap<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 QMultiMap's
++ internal data structure is optimized for fast lookup by key, not
++ by value.
++ */
++
++ /*! \fn template <class Key, class T> QList<Key> QMultiMap<Key, T>::uniqueKeys() const
++ \since 4.2
++
++ Returns a list containing all the keys in the map in ascending
++ order. Keys that occur multiple times in the map occur only
++ once in the returned list.
++ */
++
++ /*! \fn template <class Key, class T> QList<T> QMultiMap<Key, T>::values() const
++
++ Returns a list containing all the values in the map, in ascending
++ order of their keys. If a key is associated with multiple values,
++ all of its values will be in the list, and not just the most
++ recently inserted one.
++
++ \sa keys(), value()
++ */
++
++ /*! \fn template <class Key, class T> QList<T> QMultiMap<Key, T>::values(const Key &key) const
++
++ Returns a list containing all the values associated with key
++ \a key, from the most recently inserted to the least recently
++ inserted one.
++
++ \sa keys(), value()
++ */
++
++ /*! \fn template <class Key, class T> qsizetype QMultiMap<Key, T>::count() const
++
++ \overload
++
++ Same as size().
++ */
++
++ /*! \fn template <class Key, class T> qsizetype QMultiMap<Key, T>::count(const Key &key) const
++
++ Returns the number of items associated with key \a key.
++
++ \sa contains(), QMultiMap::count(const Key &key, const T &value)
++ */
++
++ /*! \fn template <class Key, class T> qsizetype QMultiMap<Key, T>::count(const Key &key, const T &value) const
++
++ Returns the number of items with key \a key and value \a value.
++
++ \sa contains(), QMultiMap::count()
++ */
++
++
++ /*! \fn template <class Key, class T> const Key &QMultiMap<Key, T>::firstKey() const
++ \since 5.2
++
++ Returns a reference to the smallest key in the multi map.
++ This function assumes that the multi map is not empty.
++
++ This executes in \l{constant time}.
++
++ \sa lastKey(), first(), keyBegin(), isEmpty()
++ */
++
++ /*! \fn template <class Key, class T> const Key &QMultiMap<Key, T>::lastKey() const
++ \since 5.2
++
++ Returns a reference to the largest key in the multi map.
++ This function assumes that the multi map is not empty.
++
++ This executes in \l{constant time}.
++
++ \sa firstKey(), last(), keyEnd(), isEmpty()
++ */
++
++ /*! \fn template <class Key, class T> T &QMultiMap<Key, T>::first()
++ \since 5.2
++
++ Returns a reference to the first value in the multi map, that is the value mapped
++ to the smallest key. This function assumes that the multi 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 &QMultiMap<Key, T>::first() const
++ \since 5.2
++
++ \overload
++ */
++
++ /*! \fn template <class Key, class T> T &QMultiMap<Key, T>::last()
++ \since 5.2
++
++ Returns a reference to the last value in the multi 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 &QMultiMap<Key, T>::last() const
++ \since 5.2
++
++ \overload
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::begin()
++
++ Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first item in
++ the multi map.
++
++ \sa constBegin(), end()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::begin() const
++
++ \overload
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::cbegin() const
++ \since 5.0
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
++ in the multi map.
++
++ \sa begin(), cend()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::constBegin() const
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
++ in the multi map.
++
++ \sa begin(), constEnd()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::key_iterator QMultiMap<Key, T>::keyBegin() const
++ \since 5.6
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first key
++ in the multi map.
++
++ \sa keyEnd(), firstKey()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::end()
++
++ Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary item
++ after the last item in the multi map.
++
++ \sa begin(), constEnd()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::end() const
++
++ \overload
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<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 multi map.
++
++ \sa cbegin(), end()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<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 multi map.
++
++ \sa constBegin(), end()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::key_iterator QMultiMap<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 multi map.
++
++ \sa keyBegin(), lastKey()
++ */
++
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::key_value_iterator QMultiMap<Key, T>::keyValueBegin()
++ \since 5.10
++
++ Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first entry
++ in the multi map.
++
++ \sa keyValueEnd()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::key_value_iterator QMultiMap<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 multi map.
++
++ \sa keyValueBegin()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_key_value_iterator QMultiMap<Key, T>::keyValueBegin() const
++ \since 5.10
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
++ in the multi map.
++
++ \sa keyValueEnd()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_key_value_iterator QMultiMap<Key, T>::constKeyValueBegin() const
++ \since 5.10
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
++ in the multi map.
++
++ \sa keyValueBegin()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_key_value_iterator QMultiMap<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 multi map.
++
++ \sa keyValueBegin()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_key_value_iterator QMultiMap<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 multi map.
++
++ \sa constKeyValueBegin()
++ */
++
++ /*! \fn template <class Key, class T> auto QMultiMap<Key, T>::asKeyValueRange() &
++ \fn template <class Key, class T> auto QMultiMap<Key, T>::asKeyValueRange() const &
++ \fn template <class Key, class T> auto QMultiMap<Key, T>::asKeyValueRange() &&
++ \fn template <class Key, class T> auto QMultiMap<Key, T>::asKeyValueRange() const &&
++ \since 6.4
++
++ Returns a range object that allows iteration over this multi 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_qmultimap.cpp 26
++
++ Note that both the key and the value obtained this way are
++ references to the ones in the multi map. Specifically, mutating the value
++ will modify the map itself.
++
++ \sa QKeyValueIterator
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::erase(const_iterator pos)
++
++ Removes the (key, value) pair pointed to by the iterator \a pos
++ from the multi map, and returns an iterator to the next item in the
++ map.
++
++ \note The iterator \a pos must be valid and dereferenceable.
++
++ \sa remove()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<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 multi map.
++ Returns an iterator to the item in the multi 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> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::find(const Key &key)
++
++ Returns an iterator pointing to the item with key \a key in the
++ multi map.
++
++ If the multi map contains no item with key \a key, the function
++ returns end().
++
++ If the map contains multiple items with key \a key, this
++ function returns an iterator that points to the most recently
++ inserted value. The other values are accessible by incrementing
++ the iterator. For example, here's some code that iterates over all
++ the items with the same key:
++
++ \snippet code/src_corelib_tools_qmultimap.cpp 11
++ \snippet code/src_corelib_tools_qmultimap.cpp 11_better
++
++ \sa constFind(), value(), values(), lowerBound(), upperBound()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::find(const Key &key) const
++
++ \overload
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::constFind(const Key &key) const
++ \since 4.1
++
++ Returns an const iterator pointing to the item with key \a key in the
++ multi map.
++
++ If the multi map contains no item with key \a key, the function
++ returns constEnd().
++
++ \sa find(), QMultiMap::constFind(const Key &key, const T &value)
++ */
++
++ /*!
++ \fn template <class Key, class T> typename QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::find(const Key &key, const T &value) const
++ \since 4.3
++ \overload
++
++ Returns a const iterator pointing to the item with the given \a key and
++ \a value in the map.
++
++ If the map contains no such item, the function returns end().
++
++ If the map contains multiple items with the specified \a key, this
++ function returns a const iterator that points to the most recently
++ inserted value.
++ */
++
++ /*!
++ \fn template <class Key, class T> typename QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::constFind(const Key &key, const T &value) const
++ \since 4.3
++
++ Returns an iterator pointing to the item with key \a key and the
++ value \a value in the map.
++
++ If the map contains no such item, the function returns
++ constEnd().
++
++ \sa QMap::constFind()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<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.
++
++ Example:
++ \snippet code/src_corelib_tools_qmultimap.cpp 15
++
++ If the map contains multiple items with key \a key, this
++ function returns an iterator that points to the most recently
++ inserted value. The other values are accessible by incrementing
++ the iterator. For example, here's some code that iterates over all
++ the items with the same key:
++
++ \snippet code/src_corelib_tools_qmultimap.cpp 16
++
++ \sa upperBound(), find()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::lowerBound(const Key &key) const
++
++ \overload
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<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_qmultimap.cpp 17
++
++ \sa lowerBound(), find()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::upperBound(const Key &key) const
++
++ \overload
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<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 same key in the map, this
++ function will simply create a new one. (This behavior is
++ different from replace(), which overwrites the value of an
++ existing item.)
++
++ QMultiMap allows duplicate keys and stores items in ascending
++ key order. For duplicate keys, the values are stored in reverse
++ insertion order (the most recently inserted value comes first).
++
++ Returns an iterator pointing to the new element.
++
++ \sa replace()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<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 multi map
++ while constEnd() suggests that the \a key is (strictly) larger than any key in the multi 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 the hint is correct and the multi map is unshared, the insert executes in amortized \l{constant time}.
++
++ If there is already an item with the same key in the map, this function will simply create a new one.
++
++ When creating a multi 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}.
++
++ Returns an iterator pointing to the new element.
++
++ \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 multi map and the \a pos multi map.
++ */
++
++ #if QT_DEPRECATED_SINCE(6, 0)
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insertMulti(const Key &key, const T &value)
++ \deprecated [6.0] Use insert() instead.
++
++ Inserts a new item with the key \a key and a value of \a value, and returns an iterator pointing to the new item.
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insertMulti(const_iterator pos, const Key &key, const T &value)
++ \deprecated [6.0] Use insert() instead.
++ \overload
++
++ Inserts a new item with the key \a key and value \a value and with hint \a pos
++ suggesting where to do the insert.
++ */
++
++ /*! \fn template <class Key, class T> void QMultiMap<Key, T>::insert(const QMultiMap<Key, T> &map)
++ \since 5.15
++ \deprecated [6.0] Use unite() instead.
++
++ Inserts all the items in \a map into this map.
++ */
++
++ /*! \fn template <class Key, class T> void QMultiMap<Key, T>::insert(QMultiMap<Key, T> &&map)
++ \since 5.15
++ \deprecated [6.0] Use unite() instead.
++ \overload
++
++ Moves all the items from \a map into this map.
++
++ If \a map is shared, then the items will be copied instead.
++ */
++ #endif
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::replace(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.
++
++ If there are multiple items with the key \a key, the most
++ recently inserted item's value is replaced with \a value.
++
++ Returns an iterator pointing to the new/updated element.
++
++ \sa insert()
++ */
++
++ /*! \typedef QMultiMap::Iterator
++
++ Qt-style synonym for QMultiMap::iterator.
++ */
++
++ /*! \typedef QMultiMap::ConstIterator
++
++ Qt-style synonym for QMultiMap::const_iterator.
++ */
++
++ /*! \typedef QMultiMap::difference_type
++
++ Typedef for ptrdiff_t. Provided for STL compatibility.
++ */
++
++ /*! \typedef QMultiMap::key_type
++
++ Typedef for Key. Provided for STL compatibility.
++ */
++
++ /*! \typedef QMultiMap::mapped_type
++
++ Typedef for T. Provided for STL compatibility.
++ */
++
++ /*! \typedef QMultiMap::size_type
++
++ Typedef for int. Provided for STL compatibility.
++ */
++
++ /*!
++ \fn template <class Key, class T> bool QMultiMap<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 QMultiMap<Key, T>::iterator, typename QMultiMap<Key, T>::iterator> QMultiMap<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 QMultiMap<Key, T>::const_iterator, typename QMultiMap<Key, T>::const_iterator> QMultiMap<Key, T>::equal_range(const Key &key) const
++ \overload
++ \since 5.6
++ */
++
++ /*!
++ \fn template <class Key, class T> QMultiMap<Key, T> &QMultiMap<Key, T>::unite(const QMultiMap<Key, T> &other)
++
++ Inserts all the items in the \a other map into this map. If a
++ key is common to both maps, the resulting map will contain the
++ key multiple times.
++ */
++
++ /*!
++ \fn template <class Key, class T> QMultiMap<Key, T> &QMultiMap<Key, T>::unite(QMultiMap<Key, T> &&other)
++
++ Moves all the items from the \a other map into this map. If a
++ key is common to both maps, the resulting map will contain the
++ key multiple times.
++
++ If \a other is shared, then the items will be copied instead.
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T> operator+=(QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
++ \relates QMultiMap
++
++ Inserts all the items in the \a rhs map into the \a lhs map and
++ returns the resulting map.
++
++ \sa insert(), operator+()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T> operator+(const QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
++ \relates QMultiMap
++
++ Returns a map that contains all the items in the \a lhs map in
++ addition to all the items in \a rhs. If a key is common to both
++ maps, the resulting map will contain the key multiple times.
++
++ \sa operator+=()
++ */
++
++ /*! \class QMultiMap::iterator
++ \inmodule QtCore
++ \brief The QMultiMap::iterator class provides an STL-style non-const iterator for QMultiMap.
++
++ QMultiMap\<Key, T\>::iterator allows you to iterate over a QMultiMap
++ and to modify the value (but not the key) stored under
++ a particular key. If you want to iterate over a const QMultiMap, you
++ should use QMultiMap::const_iterator. It is generally good practice to
++ use QMultiMap::const_iterator on a non-const QMultiMap as well, unless you
++ need to change the QMultiMap through the iterator. Const iterators are
++ slightly faster, and can improve code readability.
++
++ The default QMultiMap::iterator constructor creates an uninitialized
++ iterator. You must initialize it using a QMultiMap function like
++ QMultiMap::begin(), QMultiMap::end(), or QMultiMap::find() before you can
++ start iterating. Here's a typical loop that prints all the (key,
++ value) pairs stored in a map:
++
++ Unlike QMultiHash, which stores its items in an arbitrary order, QMultiMap
++ stores its items ordered by key. Items that share the same key
++ will appear consecutively,
++ from the most recently to the least recently inserted value.
++
++ Here's an example that increments every value stored in the QMultiMap
++ by 2:
++
++ \snippet code/src_corelib_tools_qmultimap.cpp 19
++
++ To remove elements from a QMultiMap you can use erase_if(QMultiMap\<Key, T\> &map, Predicate pred):
++
++ \snippet code/src_corelib_tools_qmultimap.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 QMultiMap::const_iterator, QMultiMap::key_iterator, QMultiMap::key_value_iterator
++ */
++
++ /*! \typedef QMultiMap::iterator::difference_type
++
++ \internal
++ */
++
++ /*! \typedef QMultiMap::iterator::iterator_category
++
++ A synonym for \e {std::bidirectional_iterator_tag} indicating
++ this iterator is a bidirectional iterator.
++ */
++
++ /*! \typedef QMultiMap::iterator::pointer
++
++ \internal
++ */
++
++ /*! \typedef QMultiMap::iterator::reference
++
++ \internal
++ */
++
++ /*! \typedef QMultiMap::iterator::value_type
++
++ \internal
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<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 QMultiMap::begin(), QMultiMap::end()
++ */
++
++ /*! \fn template <class Key, class T> const Key &QMultiMap<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 QMultiMap::erase()
++ followed by QMultiMap::insert().
++
++ \sa value()
++ */
++
++ /*! \fn template <class Key, class T> T &QMultiMap<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_qmultimap.cpp 23
++
++ \sa key(), operator*()
++ */
++
++ /*! \fn template <class Key, class T> T &QMultiMap<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 *QMultiMap<Key, T>::iterator::operator->() const
++
++ Returns a pointer to the current item's value.
++
++ \sa value()
++ */
++
++ /*!
++ \fn template<class Key, class T> bool QMultiMap<Key, T>::iterator::operator==(const iterator &lhs, const iterator &rhs)
++ \fn template<class Key, class T> bool QMultiMap<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 QMultiMap<Key, T>::iterator::operator!=(const iterator &lhs, const iterator &rhs)
++ \fn template<class Key, class T> bool QMultiMap<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> QMultiMap<Key, T>::iterator &QMultiMap<Key, T>::iterator::operator++()
++
++ The prefix \c{++} operator (\c{++i}) advances the iterator to the
++ next item in the multi map and returns an iterator to the new current
++ item.
++
++ Calling this function on QMultiMap::end() leads to undefined results.
++
++ \sa operator--()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator++(int)
++
++ \overload
++
++ The postfix \c{++} operator (\c{i++}) advances the iterator to the
++ next item in the multi map and returns an iterator to the previously
++ current item.
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator &QMultiMap<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 QMultiMap::begin() leads to undefined
++ results.
++
++ \sa operator++()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<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 [qmultimap-op-it-plus-step] template <class Key, class T> typename QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator+(QMultiMap<Key, T>::iterator, difference_type n)
++ \fn [qmultimap-op-step-plus-it] template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator+(difference_type n, QMultiMap<Key, T>::iterator)
++ \fn [qmultimap-op-it-minus-step] template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator-(QMultiMap<Key, T>::iterator, difference_type n)
++ \fn [qmultimap-op-step-minus-it] template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator-(difference_type n, QMultiMap<Key, T>::iterator)
++
++ //! members
++ \fn template <class Key, class T> typename QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator+=(QMultiMap<Key, T>::iterator::difference_type n)
++ \fn template <class Key, class T> typename QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator-=(QMultiMap<Key, T>::iterator::difference_type n)
++
++ \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
++
++ Move an iterator by \e{n} positions. These operations can be
++ expensive for large values of \e{n}; QMultiMap iterators are not
++ random access.
++ */
++
++ /*! \class QMultiMap::const_iterator
++ \inmodule QtCore
++ \brief The QMultiMap::const_iterator class provides an STL-style const iterator for QMultiMap.
++
++ QMultiMap\<Key, T\>::const_iterator allows you to iterate over a QMultiMap.
++ If you want to modify the QMultiMap as you iterate
++ over it, you must use QMultiMap::iterator instead. It is generally
++ good practice to use QMultiMap::const_iterator on a non-const QMultiMap as
++ well, unless you need to change the QMultiMap through the iterator.
++ Const iterators are slightly faster, and can improve code
++ readability.
++
++ The default QMultiMap::const_iterator constructor creates an
++ uninitialized iterator. You must initialize it using a QMultiMap
++ function like QMultiMap::cbegin(), QMultiMap::cend(), or
++ QMultiMap::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_qmultimap.cpp 24
++
++ Here's an example that removes all the items whose value is greater than 10:
++
++ \snippet code/src_corelib_tools_qmultimap.cpp 20
++
++ Unlike QMultiHash, which stores its items in an arbitrary order, QMultiMap
++ stores its items ordered by key. Items that share the same key
++ will appear consecutively,
++ from the most recently to the least recently inserted value.
++
++ Multiple iterators can be used on the same multi 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 QMultiMap::iterator, QMultiMap::key_iterator, QMultiMap::const_key_value_iterator
++ */
++
++ /*! \typedef QMultiMap::const_iterator::difference_type
++
++ \internal
++ */
++
++ /*! \typedef QMultiMap::const_iterator::iterator_category
++
++ A synonym for \e {std::bidirectional_iterator_tag} indicating
++ this iterator is a bidirectional iterator.
++ */
++
++ /*! \typedef QMultiMap::const_iterator::pointer
++
++ \internal
++ */
++
++ /*! \typedef QMultiMap::const_iterator::reference
++
++ \internal
++ */
++
++ /*! \typedef QMultiMap::const_iterator::value_type
++
++ \internal
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<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 QMultiMap::constBegin(), QMultiMap::constEnd()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator::const_iterator(const iterator &other)
++
++ Constructs a copy of \a other.
++ */
++
++ /*! \fn template <class Key, class T> const Key &QMultiMap<Key, T>::const_iterator::key() const
++
++ Returns the current item's key.
++
++ \sa value()
++ */
++
++ /*! \fn template <class Key, class T> const T &QMultiMap<Key, T>::const_iterator::value() const
++
++ Returns the current item's value.
++
++ \sa key(), operator*()
++ */
++
++ /*! \fn template <class Key, class T> const T &QMultiMap<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 *QMultiMap<Key, T>::const_iterator::operator->() const
++
++ Returns a pointer to the current item's value.
++
++ \sa value()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator &QMultiMap<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 QMultiMap::end() leads to undefined results.
++
++ \sa operator--()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<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> QMultiMap<Key, T>::const_iterator &QMultiMap<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 QMultiMap::begin() leads to undefined
++ results.
++
++ \sa operator++()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<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 [qmultimap-op-it-plus-step-const] template <class Key, class T> typename QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator+(QMultiMap<Key, T>::const_iterator, difference_type n)
++ \fn [qmultimap-op-step-plus-it-const] template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator+(difference_type n, QMultiMap<Key, T>::const_iterator)
++ \fn [qmultimap-op-it-minus-step-const] template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator-(QMultiMap<Key, T>::const_iterator, difference_type n)
++ \fn [qmultimap-op-step-minus-it-const] template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator-(difference_type n, QMultiMap<Key, T>::const_iterator)
++
++ //! members
++ \fn template <class Key, class T> typename QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator+=(QMultiMap<Key, T>::const_iterator::difference_type n)
++ \fn template <class Key, class T> typename QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator-=(QMultiMap<Key, T>::const_iterator::difference_type n)
++
++ \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
++
++ Move an iterator by \e{n} positions. These operations can be
++ expensive for large values of \e{n}. QMultiMap iterators are not
++ random access.
++ */
++
++ /*! \class QMultiMap::key_iterator
++ \inmodule QtCore
++ \since 5.6
++ \brief The QMultiMap::key_iterator class provides an STL-style const iterator for QMultiMap keys.
++
++ QMultiMap::key_iterator is essentially the same as QMultiMap::const_iterator
++ with the difference that operator*() and operator->() return a key
++ instead of a value.
++
++ For most uses QMultiMap::iterator and QMultiMap::const_iterator should be used,
++ you can easily access the key by calling QMultiMap::iterator::key():
++
++ \snippet code/src_corelib_tools_qmultimap.cpp keyiterator1
++
++ However, to have interoperability between QMultiMap's keys and STL-style
++ algorithms we need an iterator that dereferences to a key instead
++ of a value. With QMultiMap::key_iterator we can apply an algorithm to a
++ range of keys without having to call QMultiMap::keys(), which is inefficient
++ as it costs one QMultiMap iteration and memory allocation to create a temporary
++ QList.
++
++ \snippet code/src_corelib_tools_qmultimap.cpp keyiterator2
++
++ QMultiMap::key_iterator is const, it's not possible to modify the key.
++
++ The default QMultiMap::key_iterator constructor creates an uninitialized
++ iterator. You must initialize it using a QMultiMap function like
++ QMultiMap::keyBegin() or QMultiMap::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 QMultiMap::const_iterator, QMultiMap::iterator
++ */
++
++ /*! \typedef QMultiMap::key_iterator::difference_type
++ \internal
++ */
++
++ /*! \typedef QMultiMap::key_iterator::iterator_category
++ \internal
++ */
++
++ /*! \typedef QMultiMap::key_iterator::pointer
++ \internal
++ */
++
++ /*! \typedef QMultiMap::key_iterator::reference
++ \internal
++ */
++
++ /*! \typedef QMultiMap::key_iterator::value_type
++ \internal
++ */
++
++ /*! \fn template <class Key, class T> const T &QMultiMap<Key, T>::key_iterator::operator*() const
++
++ Returns the current item's key.
++ */
++
++ /*! \fn template <class Key, class T> const T *QMultiMap<Key, T>::key_iterator::operator->() const
++
++ Returns a pointer to the current item's key.
++ */
++
++ /*! \fn template <class Key, class T> bool QMultiMap<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 QMultiMap<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> QMultiMap<Key, T>::key_iterator &QMultiMap<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 QMultiMap::keyEnd() leads to undefined results.
++
++ \sa operator--()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::key_iterator QMultiMap<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> QMultiMap<Key, T>::key_iterator &QMultiMap<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 QMultiMap::keyBegin() leads to undefined
++ results.
++
++ \sa operator++()
++ */
++
++ /*! \fn template <class Key, class T> QMultiMap<Key, T>::key_iterator QMultiMap<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 QMultiMap<Key, T>::key_iterator::base() const
++ Returns the underlying const_iterator this key_iterator is based on.
++ */
++
++ /*! \typedef QMultiMap::const_key_value_iterator
++ \inmodule QtCore
++ \since 5.10
++ \brief The QMultiMap::const_key_value_iterator typedef provides an STL-style iterator for QMultiMap.
++
++ QMultiMap::const_key_value_iterator is essentially the same as QMultiMap::const_iterator
++ with the difference that operator*() returns a key/value pair instead of a
++ value.
++
++ \sa QKeyValueIterator
++ */
++
++ /*! \typedef QMultiMap::key_value_iterator
++ \inmodule QtCore
++ \since 5.10
++ \brief The QMultiMap::key_value_iterator typedef provides an STL-style iterator for QMultiMap.
++
++ QMultiMap::key_value_iterator is essentially the same as QMultiMap::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 QMultiMap<Key, T> &map)
++ \relates QMultiMap
++
++ Writes the multi 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, QMultiMap<Key, T> &map)
++ \relates QMultiMap
++
++ 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(QMultiMap<Key, T> &map, Predicate pred)
++ \relates QMultiMap
++ \since 6.1
++
++ Removes all elements for which the predicate \a pred returns true
++ from the multi map \a map.
++
++ The function supports predicates which take either an argument of
++ type \c{QMultiMap<Key, T>::iterator}, or an argument of type
++ \c{std::pair<const Key &, T &>}.
++
++ Returns the number of elements removed, if any.
++ */