1// Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
2// Copyright (C) 2016 The Qt Company Ltd.
3// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
8 \brief The QMap class is a template class that provides an associative array.
15 QMap<Key, T> is one of Qt's generic \l{container classes}. It
16 stores (key, value) pairs and provides fast lookup by key.
18 QMap and QHash provide very similar functionality. The
22 \li QHash provides average faster lookups than QMap. (See \l{Algorithmic
23 Complexity} for details.)
24 \li When iterating over a QHash, the items are arbitrarily ordered.
25 With QMap, the items are always sorted by key.
26 \li The key type of a QHash must provide operator==() and a global
27 qHash(Key) function. The key type of a QMap must provide
28 operator<() specifying a total order. Since Qt 5.8.1 it is also safe
29 to use a pointer type as key, even if the underlying operator<()
30 does not provide a total order.
33 Here's an example QMap with QString keys and \c int values:
34 \snippet code/src_corelib_tools_qmap.cpp 0
36 To insert a (key, value) pair into the map, you can use operator[]():
38 \snippet code/src_corelib_tools_qmap.cpp 1
40 This inserts the following three (key, value) pairs into the
41 QMap: ("one", 1), ("three", 3), and ("seven", 7). Another way to
42 insert items into the map is to use insert():
44 \snippet code/src_corelib_tools_qmap.cpp 2
46 To look up a value, use operator[]() or value():
48 \snippet code/src_corelib_tools_qmap.cpp 3
50 If there is no item with the specified key in the map, these
51 functions return a \l{default-constructed value}.
53 If you want to check whether the map contains a certain key, use
56 \snippet code/src_corelib_tools_qmap.cpp 4
58 There is also a value() overload that uses its second argument as
59 a default value if there is no item with the specified key:
61 \snippet code/src_corelib_tools_qmap.cpp 5
63 In general, we recommend that you use contains() and value()
64 rather than operator[]() for looking up a key in a map. The
65 reason is that operator[]() silently inserts an item into the
66 map if no item exists with the same key (unless the map is
67 const). For example, the following code snippet will create 1000
70 \snippet code/src_corelib_tools_qmap.cpp 6
72 To avoid this problem, replace \c map[i] with \c map.value(i)
75 If you want to navigate through all the (key, value) pairs stored
76 in a QMap, you can use an iterator. QMap provides both
77 \l{Java-style iterators} (QMapIterator and QMutableMapIterator)
78 and \l{STL-style iterators} (QMap::const_iterator and
79 QMap::iterator). Here's how to iterate over a QMap<QString, int>
80 using a Java-style iterator:
82 \snippet code/src_corelib_tools_qmap.cpp 7
84 Here's the same code, but using an STL-style iterator this time:
86 \snippet code/src_corelib_tools_qmap.cpp 8
88 The items are traversed in ascending key order.
90 A QMap allows only one value per key. If you call
91 insert() with a key that already exists in the QMap, the
92 previous value will be erased. For example:
94 \snippet code/src_corelib_tools_qmap.cpp 9
96 However, you can store multiple values per key by using
99 If you only need to extract the values from a map (not the keys),
100 you can also use range-based for:
102 \snippet code/src_corelib_tools_qmap.cpp 12
104 Items can be removed from the map in several ways. One way is to
105 call remove(); this will remove any item with the given key.
106 Another way is to use QMutableMapIterator::remove(). In addition,
107 you can clear the entire map using clear().
109 QMap's key and value data types must be \l{assignable data
110 types}. This covers most data types you are likely to encounter,
111 but the compiler won't let you, for example, store a QWidget as a
112 value; instead, store a QWidget *. In addition, QMap's key type
113 must provide operator<(). QMap uses it to keep its items sorted,
114 and assumes that two keys \c x and \c y are equivalent if neither \c{x
115 < y} nor \c{y < x} is true.
118 \snippet code/src_corelib_tools_qmap.cpp 13
120 In the example, we start by comparing the employees' names. If
121 they're equal, we compare their dates of birth to break the tie.
123 \sa QMapIterator, QMutableMapIterator, QHash, QSet
126/*! \fn template <class Key, class T> QMap<Key, T>::QMap()
128 Constructs an empty map.
133/*! \fn template <class Key, class T> QMap<Key, T>::QMap(const QMap<Key, T> &other)
135 Constructs a copy of \a other.
137 This operation occurs in \l{constant time}, because QMap is
138 \l{implicitly shared}. This makes returning a QMap from a
139 function very fast. If a shared instance is modified, it will be
140 copied (copy-on-write), and this takes \l{linear time}.
146 \fn template <class Key, class T> QMap<Key, T>::QMap(QMap<Key, T> &&other)
148 Move-constructs a QMap instance.
153/*! \fn template <class Key, class T> QMap<Key, T> &QMap<Key, T>::operator=(const QMap<Key, T> &other)
155 Assigns \a other to this map and returns a reference to this map.
159 \fn template <class Key, class T> QMap<Key, T> &QMap<Key, T>::operator=(QMap<Key, T> &&other)
161 Move-assigns \a other to this QMap instance.
166/*! \fn template <class Key, class T> QMap<Key, T>::~QMap()
168 Destroys the map. References to the values in the map, and all
169 iterators over this map, become invalid.
172/*! \fn template <class Key, class T> void QMap<Key, T>::swap(QMap<Key, T> &other) noexcept
175 Swaps map \a other with this map. This operation is very
176 fast and never fails.
179/*! \fn template <class Key, class T> QMap<Key, T>::QMap(std::initializer_list<std::pair<Key,T> > list)
182 Constructs a map with a copy of each of the elements in the
183 initializer list \a list.
186/*! \fn template <class Key, class T> QMap<Key, T>::QMap(const std::map<Key, T> & other)
188 Constructs a copy of \a other.
193/*! \fn template <class Key, class T> QMap<Key, T>::QMap(std::map<Key, T> && other)
195 Constructs a map by moving from \a other.
200/*! \fn template <class Key, class T> std::map<Key, T> QMap<Key, T>::toStdMap() const &
202 Returns an STL map equivalent to this QMap.
205/*! \fn template <class Key, class T> std::map<Key, T> QMap<Key, T>::toStdMap() &&
210 \note Calling this function will leave this QMap in the partially-formed state, in which
211 the only valid operations are destruction or assignment of a new value.
214/*! \fn template <class Key, class T> bool QMap<Key, T>::operator==(const QMap<Key, T> &lhs, const QMap<Key, T> &rhs)
216 Returns \c true if \a lhs is equal to \a rhs; otherwise returns
219 Two maps are considered equal if they contain the same (key,
222 This function requires the key and the value types to implement \c
228/*! \fn template <class Key, class T> bool QMap<Key, T>::operator!=(const QMap<Key, T> &lhs, const QMap<Key, T> &rhs)
230 Returns \c true if \a lhs is not equal to \a rhs; otherwise returns
233 Two maps are considered equal if they contain the same (key,
236 This function requires the key and the value types to implement \c
242/*! \fn template <class Key, class T> size_type QMap<Key, T>::size() const
244 Returns the number of (key, value) pairs in the map.
246 \sa isEmpty(), count()
250 \fn template <class Key, class T> bool QMap<Key, T>::isEmpty() const
252 Returns \c true if the map contains no items; otherwise returns
258/*! \fn template <class Key, class T> void QMap<Key, T>::detach()
262 Detaches this map from any other maps with which it may share
268/*! \fn template <class Key, class T> bool QMap<Key, T>::isDetached() const
272 Returns \c true if the map's internal data isn't shared with any
273 other map object; otherwise returns \c false.
278/*! \fn template <class Key, class T> bool QMap<Key, T>::isSharedWith(const QMap<Key, T> &other) const
283/*! \fn template <class Key, class T> void QMap<Key, T>::clear()
285 Removes all items from the map.
290/*! \fn template <class Key, class T> size_type QMap<Key, T>::remove(const Key &key)
292 Removes all the items that have the key \a key from the map.
293 Returns the number of items removed which will be 1 if the key
294 exists in the map, and 0 otherwise.
299/*! \fn template <class Key, class T> template <typename Predicate> size_type QMap<Key, T>::removeIf(Predicate pred)
302 Removes all elements for which the predicate \a pred returns true
305 The function supports predicates which take either an argument of
306 type \c{QMap<Key, T>::iterator}, or an argument of type
307 \c{std::pair<const Key &, T &>}.
309 Returns the number of elements removed, if any.
314/*! \fn template <class Key, class T> T QMap<Key, T>::take(const Key &key)
316 Removes the item with the key \a key from the map and returns
317 the value associated with it.
319 If the item does not exist in the map, the function simply
320 returns a \l{default-constructed value}.
322 If you don't use the return value, remove() is more efficient.
327/*! \fn template <class Key, class T> bool QMap<Key, T>::contains(const Key &key) const
329 Returns \c true if the map contains an item with key \a key;
330 otherwise returns \c false.
336 \fn template <class Key, class T> Key QMap<Key, T>::key(const T &value, const Key &defaultKey) const
340 Returns the first key with value \a value, or \a defaultKey if
341 the map contains no item with value \a value. If no \a defaultKey
342 is provided the function returns a
343 \l{default-constructed value}{default-constructed key}.
345 This function can be slow (\l{linear time}), because QMap's
346 internal data structure is optimized for fast lookup by key, not
352/*! \fn template <class Key, class T> T QMap<Key, T>::value(const Key &key, const T &defaultValue) const
354 Returns the value associated with the key \a key.
356 If the map contains no item with key \a key, the function returns
357 \a defaultValue. If no \a defaultValue is specified, the function
358 returns a \l{default-constructed value}.
360 \sa key(), values(), contains(), operator[]()
363/*! \fn template <class Key, class T> T &QMap<Key, T>::operator[](const Key &key)
365 Returns the value associated with the key \a key as a modifiable
368 If the map contains no item with key \a key, the function inserts
369 a \l{default-constructed value} into the map with key \a key, and
370 returns a reference to it.
372 \sa insert(), value()
375/*! \fn template <class Key, class T> T QMap<Key, T>::operator[](const Key &key) const
382/*! \fn template <class Key, class T> QList<Key> QMap<Key, T>::keys() const
384 Returns a list containing all the keys in the map in ascending
387 The order is guaranteed to be the same as that used by values().
389 This function creates a new list, in \l {linear time}. The time and memory
390 use that entails can be avoided by iterating from \l keyBegin() to
396/*! \fn template <class Key, class T> QList<Key> QMap<Key, T>::keys(const T &value) const
400 Returns a list containing all the keys associated with value \a
401 value in ascending order.
403 This function can be slow (\l{linear time}), because QMap's
404 internal data structure is optimized for fast lookup by key, not
408/*! \fn template <class Key, class T> QList<T> QMap<Key, T>::values() const
410 Returns a list containing all the values in the map, in ascending
413 This function creates a new list, in \l {linear time}. The time and memory
414 use that entails can be avoided by iterating from \l keyValueBegin() to
420/*! \fn template <class Key, class T> size_type QMap<Key, T>::count(const Key &key) const
422 Returns the number of items associated with key \a key.
427/*! \fn template <class Key, class T> size_type QMap<Key, T>::count() const
434/*! \fn template <class Key, class T> const Key &QMap<Key, T>::firstKey() const
437 Returns a reference to the smallest key in the map.
438 This function assumes that the map is not empty.
440 This executes in \l{constant time}.
442 \sa lastKey(), first(), keyBegin(), isEmpty()
445/*! \fn template <class Key, class T> const Key &QMap<Key, T>::lastKey() const
448 Returns a reference to the largest key in the map.
449 This function assumes that the map is not empty.
451 This executes in \l{logarithmic time}.
453 \sa firstKey(), last(), keyEnd(), isEmpty()
456/*! \fn template <class Key, class T> T &QMap<Key, T>::first()
459 Returns a reference to the first value in the map, that is the value mapped
460 to the smallest key. This function assumes that the map is not empty.
462 When unshared (or const version is called), this executes in \l{constant time}.
464 \sa last(), firstKey(), isEmpty()
467/*! \fn template <class Key, class T> const T &QMap<Key, T>::first() const
473/*! \fn template <class Key, class T> T &QMap<Key, T>::last()
476 Returns a reference to the last value in the map, that is the value mapped
477 to the largest key. This function assumes that the map is not empty.
479 When unshared (or const version is called), this executes in \l{logarithmic time}.
481 \sa first(), lastKey(), isEmpty()
484/*! \fn template <class Key, class T> const T &QMap<Key, T>::last() const
490/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::begin()
492 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first item in
495 \sa constBegin(), end()
498/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::begin() const
503/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::cbegin() const
506 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
512/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::constBegin() const
514 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
517 \sa begin(), constEnd()
520/*! \fn template <class Key, class T> QMap<Key, T>::key_iterator QMap<Key, T>::keyBegin() const
523 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first key
526 \sa keyEnd(), firstKey()
529/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::end()
531 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary item
532 after the last item in the map.
534 \sa begin(), constEnd()
537/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::end() const
542/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::cend() const
545 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
546 item after the last item in the map.
551/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::constEnd() const
553 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
554 item after the last item in the map.
556 \sa constBegin(), end()
559/*! \fn template <class Key, class T> QMap<Key, T>::key_iterator QMap<Key, T>::keyEnd() const
562 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
563 item after the last key in the map.
565 \sa keyBegin(), lastKey()
569/*! \fn template <class Key, class T> QMap<Key, T>::key_value_iterator QMap<Key, T>::keyValueBegin()
572 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first entry
578/*! \fn template <class Key, class T> QMap<Key, T>::key_value_iterator QMap<Key, T>::keyValueEnd()
581 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
582 entry after the last entry in the map.
587/*! \fn template <class Key, class T> QMap<Key, T>::const_key_value_iterator QMap<Key, T>::keyValueBegin() const
590 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
596/*! \fn template <class Key, class T> QMap<Key, T>::const_key_value_iterator QMap<Key, T>::constKeyValueBegin() const
599 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
605/*! \fn template <class Key, class T> QMap<Key, T>::const_key_value_iterator QMap<Key, T>::keyValueEnd() const
608 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
609 entry after the last entry in the map.
614/*! \fn template <class Key, class T> QMap<Key, T>::const_key_value_iterator QMap<Key, T>::constKeyValueEnd() const
617 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
618 entry after the last entry in the map.
620 \sa constKeyValueBegin()
623/*! \fn template <class Key, class T> auto QMap<Key, T>::asKeyValueRange() &
624 \fn template <class Key, class T> auto QMap<Key, T>::asKeyValueRange() const &
625 \fn template <class Key, class T> auto QMap<Key, T>::asKeyValueRange() &&
626 \fn template <class Key, class T> auto QMap<Key, T>::asKeyValueRange() const &&
629 Returns a range object that allows iteration over this map as
630 key/value pairs. For instance, this range object can be used in a
631 range-based for loop, in combination with a structured binding declaration:
633 \snippet code/src_corelib_tools_qmap.cpp 28
635 Note that both the key and the value obtained this way are
636 references to the ones in the map. Specifically, mutating the value
637 will modify the map itself.
639 \sa QKeyValueIterator
642/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::erase(const_iterator pos)
644 Removes the (key, value) pair pointed to by the iterator \a pos
645 from the map, and returns an iterator to the next item in the
648 \note The iterator \a pos \e must be valid and dereferenceable.
653/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::erase(const_iterator first, const_iterator last)
656 Removes the (key, value) pairs pointed to by the iterator range
657 [\a first, \a last) from the map.
658 Returns an iterator to the item in the map following the last removed element.
660 \note The range \c {[first, last)} \e must be a valid range in \c {*this}.
665/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::find(const Key &key)
667 Returns an iterator pointing to the item with key \a key in the
670 If the map contains no item with key \a key, the function
673 \sa constFind(), value(), values(), lowerBound(), upperBound()
676/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::find(const Key &key) const
681/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::constFind(const Key &key) const
684 Returns an const iterator pointing to the item with key \a key in the
687 If the map contains no item with key \a key, the function
693/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::lowerBound(const Key &key)
695 Returns an iterator pointing to the first item with key \a key in
696 the map. If the map contains no item with key \a key, the
697 function returns an iterator to the nearest item with a greater
700 \sa upperBound(), find()
703/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::lowerBound(const Key &key) const
708/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::upperBound(const Key &key)
710 Returns an iterator pointing to the item that immediately follows
711 the last item with key \a key in the map. If the map contains no
712 item with key \a key, the function returns an iterator to the
713 nearest item with a greater key.
716 \snippet code/src_corelib_tools_qmap.cpp 17
718 \sa lowerBound(), find()
721/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::upperBound(const Key &key) const
726/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::insert(const Key &key, const T &value)
728 Inserts a new item with the key \a key and a value of \a value.
730 If there is already an item with the key \a key, that item's value
731 is replaced with \a value.
733 Returns an iterator pointing to the new/updated element.
736/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::insert(const_iterator pos, const Key &key, const T &value)
739 Inserts a new item with the key \a key and value \a value and with hint \a pos
740 suggesting where to do the insert.
742 If constBegin() is used as hint it indicates that the \a key is less than any key in the map
743 while constEnd() suggests that the \a key is (strictly) larger than any key in the map.
744 Otherwise the hint should meet the condition (\a pos - 1).key() < \a key <= pos.key().
745 If the hint \a pos is wrong it is ignored and a regular insert is done.
747 If there is already an item with the key \a key, that item's value
748 is replaced with \a value.
750 If the hint is correct and the map is unshared, the insert executes in amortized \l{constant time}.
752 When creating a map from sorted data inserting the largest key first with constBegin()
753 is faster than inserting in sorted order with constEnd(), since constEnd() - 1 (which is needed
754 to check if the hint is valid) needs \l{logarithmic time}.
756 \b {Note:} Be careful with the hint. Providing an iterator from an older shared instance might
757 crash but there is also a risk that it will silently corrupt both the map and the \a pos map.
759 Returns an iterator pointing to the new/updated element.
762/*! \fn template <class Key, class T> void QMap<Key, T>::insert(const QMap<Key, T> &map)
765 Inserts all the items in \a map into this map.
767 If a key is common to both maps, its value will be replaced with
768 the value stored in \a map.
771/*! \fn template <class Key, class T> void QMap<Key, T>::insert(QMap<Key, T> &&map)
774 Moves all the items from \a map into this map.
776 If a key is common to both maps, its value will be replaced with
777 the value stored in \a map.
779 If \a map is shared, then the items will be copied instead.
782/*! \typedef QMap::Iterator
784 Qt-style synonym for QMap::iterator.
787/*! \typedef QMap::ConstIterator
789 Qt-style synonym for QMap::const_iterator.
792/*! \typedef QMap::difference_type
794 Typedef for ptrdiff_t. Provided for STL compatibility.
797/*! \typedef QMap::key_type
799 Typedef for Key. Provided for STL compatibility.
802/*! \typedef QMap::mapped_type
804 Typedef for T. Provided for STL compatibility.
807/*! \typedef QMap::size_type
809 Typedef for int. Provided for STL compatibility.
813 \fn template <class Key, class T> bool QMap<Key, T>::empty() const
815 This function is provided for STL compatibility. It is equivalent
816 to isEmpty(), returning true if the map is empty; otherwise
821 \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)
823 Returns a pair of iterators delimiting the range of values \c{[first, second)}, that
824 are stored under \a key.
828 \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
834/*! \class QMap::iterator
836 \brief The QMap::iterator class provides an STL-style non-const iterator for QMap.
838 QMap<Key, T>::iterator allows you to iterate over a QMap
839 and to modify the value (but not the key) stored under
840 a particular key. If you want to iterate over a const QMap, you
841 should use QMap::const_iterator. It is generally good practice to
842 use QMap::const_iterator on a non-const QMap as well, unless you
843 need to change the QMap through the iterator. Const iterators are
844 slightly faster, and can improve code readability.
846 The default QMap::iterator constructor creates an uninitialized
847 iterator. You must initialize it using a QMap function like
848 QMap::begin(), QMap::end(), or QMap::find() before you can
849 start iterating. Here's a typical loop that prints all the (key,
850 value) pairs stored in a map:
852 \snippet code/src_corelib_tools_qmap.cpp 18
854 Unlike QHash, which stores its items in an arbitrary order, QMap
855 stores its items ordered by key.
857 Here's an example that increments every value stored in the QMap
860 \snippet code/src_corelib_tools_qmap.cpp 19
862 To remove elements from a QMap you can use erase_if(QMap<Key, T> &map, Predicate pred):
864 \snippet code/src_corelib_tools_qmap.cpp 21
866 Multiple iterators can be used on the same map. If you add items
867 to the map, existing iterators will remain valid. If you remove
868 items from the map, iterators that point to the removed items
869 will become dangling iterators.
871 \warning Iterators on implicitly shared containers do not work
872 exactly like STL-iterators. You should avoid copying a container
873 while iterators are active on that container. For more information,
874 read \l{Implicit sharing iterator problem}.
876 \sa QMap::const_iterator, QMap::key_iterator, QMap::key_value_iterator
879/*! \typedef QMap::iterator::difference_type
884/*! \typedef QMap::iterator::iterator_category
886 A synonym for \e {std::bidirectional_iterator_tag} indicating
887 this iterator is a bidirectional iterator.
890/*! \typedef QMap::iterator::pointer
895/*! \typedef QMap::iterator::reference
900/*! \typedef QMap::iterator::value_type
905/*! \fn template <class Key, class T> QMap<Key, T>::iterator::iterator()
907 Constructs an uninitialized iterator.
909 Functions like key(), value(), and operator++() must not be
910 called on an uninitialized iterator. Use operator=() to assign a
911 value to it before using it.
913 \sa QMap::begin(), QMap::end()
916/*! \fn template <class Key, class T> const Key &QMap<Key, T>::iterator::key() const
918 Returns the current item's key as a const reference.
920 There is no direct way of changing an item's key through an
921 iterator, although it can be done by calling QMap::erase()
922 followed by QMap::insert().
927/*! \fn template <class Key, class T> T &QMap<Key, T>::iterator::value() const
929 Returns a modifiable reference to the current item's value.
931 You can change the value of an item by using value() on
932 the left side of an assignment, for example:
934 \snippet code/src_corelib_tools_qmap.cpp 23
936 \sa key(), operator*()
939/*! \fn template <class Key, class T> T &QMap<Key, T>::iterator::operator*() const
941 Returns a modifiable reference to the current item's value.
948/*! \fn template <class Key, class T> T *QMap<Key, T>::iterator::operator->() const
950 Returns a pointer to the current item's value.
956 \fn template <class Key, class T> bool QMap<Key, T>::iterator::operator==(const iterator &lhs, const iterator &rhs)
957 \fn template <class Key, class T> bool QMap<Key, T>::const_iterator::operator==(const const_iterator &lhs, const const_iterator &rhs)
959 Returns \c true if \a lhs points to the same item as the \a rhs iterator;
960 otherwise returns \c false.
966 \fn template <class Key, class T> bool QMap<Key, T>::iterator::operator!=(const iterator &lhs, const iterator &rhs)
967 \fn template <class Key, class T> bool QMap<Key, T>::const_iterator::operator!=(const const_iterator &lhs, const const_iterator &rhs)
969 Returns \c true if \a lhs points to a different item than the \a rhs iterator;
970 otherwise returns \c false.
975/*! \fn template <class Key, class T> QMap<Key, T>::iterator &QMap<Key, T>::iterator::operator++()
977 The prefix \c{++} operator (\c{++i}) advances the iterator to the
978 next item in the map and returns an iterator to the new current
981 Calling this function on QMap::end() leads to undefined results.
986/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator++(int)
990 The postfix \c{++} operator (\c{i++}) advances the iterator to the
991 next item in the map and returns an iterator to the previously
995/*! \fn template <class Key, class T> QMap<Key, T>::iterator &QMap<Key, T>::iterator::operator--()
997 The prefix \c{--} operator (\c{--i}) makes the preceding item
998 current and returns an iterator pointing to the new current item.
1000 Calling this function on QMap::begin() leads to undefined
1006/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator--(int)
1010 The postfix \c{--} operator (\c{i--}) makes the preceding item
1011 current and returns an iterator pointing to the previously
1016 \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)
1017 \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)
1018 \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)
1019 \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)
1022 \fn template <class Key, class T> typename QMap<Key, T>::iterator QMap<Key, T>::iterator::operator+=(QMap<Key, T>::iterator::difference_type n)
1023 \fn template <class Key, class T> typename QMap<Key, T>::iterator QMap<Key, T>::iterator::operator-=(QMap<Key, T>::iterator::difference_type n)
1025 \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
1027 Moves an iterator by \e{n} positions. These operations can be
1028 expensive for large values of \e{n}; QMap iterators are not
1032/*! \class QMap::const_iterator
1034 \brief The QMap::const_iterator class provides an STL-style const iterator for QMap.
1036 QMap<Key, T>::const_iterator allows you to iterate over a QMap.
1037 If you want to modify the QMap as you iterate
1038 over it, you must use QMap::iterator instead. It is generally
1039 good practice to use QMap::const_iterator on a non-const QMap as
1040 well, unless you need to change the QMap through the iterator.
1041 Const iterators are slightly faster, and can improve code
1044 The default QMap::const_iterator constructor creates an
1045 uninitialized iterator. You must initialize it using a QMap
1046 function like QMap::cbegin(), QMap::cend(), or
1047 QMap::constFind() before you can start iterating. Here's a typical
1048 loop that prints all the (key, value) pairs stored in a map:
1050 \snippet code/src_corelib_tools_qmap.cpp 24
1052 Here's an example that removes all the items whose value is greater than 10:
1054 \snippet code/src_corelib_tools_qmap.cpp 20
1056 And here the same behavior with erase_if()
1058 \snippet code/src_corelib_tools_qmap.cpp 21
1060 Unlike QHash, which stores its items in an arbitrary order, QMap
1061 stores its items ordered by key.
1063 Multiple iterators can be used on the same map. If you add items
1064 to the map, existing iterators will remain valid. If you remove
1065 items from the map, iterators that point to the removed items
1066 will become dangling iterators.
1068 \warning Iterators on implicitly shared containers do not work
1069 exactly like STL-iterators. You should avoid copying a container
1070 while iterators are active on that container. For more information,
1071 read \l{Implicit sharing iterator problem}.
1073 \sa QMap::iterator, QMap::key_iterator, QMap::const_key_value_iterator
1076/*! \typedef QMap::const_iterator::difference_type
1081/*! \typedef QMap::const_iterator::iterator_category
1083 A synonym for \e {std::bidirectional_iterator_tag} indicating
1084 this iterator is a bidirectional iterator.
1087/*! \typedef QMap::const_iterator::pointer
1092/*! \typedef QMap::const_iterator::reference
1097/*! \typedef QMap::const_iterator::value_type
1102/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator::const_iterator()
1104 Constructs an uninitialized iterator.
1106 Functions like key(), value(), and operator++() must not be
1107 called on an uninitialized iterator. Use operator=() to assign a
1108 value to it before using it.
1110 \sa QMap::constBegin(), QMap::constEnd()
1113/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator::const_iterator(const iterator &other)
1115 Constructs a copy of \a other.
1118/*! \fn template <class Key, class T> const Key &QMap<Key, T>::const_iterator::key() const
1120 Returns the current item's key.
1125/*! \fn template <class Key, class T> const T &QMap<Key, T>::const_iterator::value() const
1127 Returns the current item's value.
1129 \sa key(), operator*()
1132/*! \fn template <class Key, class T> const T &QMap<Key, T>::const_iterator::operator*() const
1134 Returns the current item's value.
1141/*! \fn template <class Key, class T> const T *QMap<Key, T>::const_iterator::operator->() const
1143 Returns a pointer to the current item's value.
1148/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator &QMap<Key, T>::const_iterator::operator++()
1150 The prefix \c{++} operator (\c{++i}) advances the iterator to the
1151 next item in the map and returns an iterator to the new current
1154 Calling this function on QMap::end() leads to undefined results.
1159/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator++(int)
1163 The postfix \c{++} operator (\c{i++}) advances the iterator to the
1164 next item in the map and returns an iterator to the previously
1168/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator &QMap<Key, T>::const_iterator::operator--()
1170 The prefix \c{--} operator (\c{--i}) makes the preceding item
1171 current and returns an iterator pointing to the new current item.
1173 Calling this function on QMap::begin() leads to undefined
1179/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator--(int)
1183 The postfix \c{--} operator (\c{i--}) makes the preceding item
1184 current and returns an iterator pointing to the previously
1189 \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)
1190 \fn [qmap-op-step-plus-it-const] template <class Key, class T> QMap<Key, T>::operator+(difference_type n, QMap<Key, T>::const_iterator)
1191 \fn [qmap-op-it-minus-step-const] template <class Key, class T> QMap<Key, T>::operator-(QMap<Key, T>::const_iterator, difference_type n)
1192 \fn [qmap-op-step-minus-it-const] template <class Key, class T> QMap<Key, T>::operator-(difference_type n, QMap<Key, T>::const_iterator)
1195 \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)
1196 \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)
1198 \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
1200 Moves an iterator by \e{n} positions. These operations can be
1201 expensive for large values of \e{n}. QMap iterators are not
1205/*! \class QMap::key_iterator
1208 \brief The QMap::key_iterator class provides an STL-style const iterator for QMap keys.
1210 QMap::key_iterator is essentially the same as QMap::const_iterator
1211 with the difference that operator*() and operator->() return a key
1214 For most uses QMap::iterator and QMap::const_iterator should be used,
1215 you can easily access the key by calling QMap::iterator::key():
1217 \snippet code/src_corelib_tools_qmap.cpp keyiterator1
1219 However, to have interoperability between QMap's keys and STL-style
1220 algorithms we need an iterator that dereferences to a key instead
1221 of a value. With QMap::key_iterator we can apply an algorithm to a
1222 range of keys without having to call QMap::keys(), which is inefficient
1223 as it costs one QMap iteration and memory allocation to create a temporary
1226 \snippet code/src_corelib_tools_qmap.cpp keyiterator2
1228 QMap::key_iterator is const, it's not possible to modify the key.
1230 The default QMap::key_iterator constructor creates an uninitialized
1231 iterator. You must initialize it using a QMap function like
1232 QMap::keyBegin() or QMap::keyEnd().
1234 \warning Iterators on implicitly shared containers do not work
1235 exactly like STL-iterators. You should avoid copying a container
1236 while iterators are active on that container. For more information,
1237 read \l{Implicit sharing iterator problem}.
1239 \sa QMap::const_iterator, QMap::iterator
1242/*! \typedef QMap::key_iterator::difference_type
1246/*! \typedef QMap::key_iterator::iterator_category
1250/*! \typedef QMap::key_iterator::pointer
1254/*! \typedef QMap::key_iterator::reference
1258/*! \typedef QMap::key_iterator::value_type
1262/*! \fn template <class Key, class T> const T &QMap<Key, T>::key_iterator::operator*() const
1264 Returns the current item's key.
1267/*! \fn template <class Key, class T> const T *QMap<Key, T>::key_iterator::operator->() const
1269 Returns a pointer to the current item's key.
1272/*! \fn template <class Key, class T> bool QMap<Key, T>::key_iterator::operator==(key_iterator other) const
1274 Returns \c true if \a other points to the same item as this
1275 iterator; otherwise returns \c false.
1280/*! \fn template <class Key, class T> bool QMap<Key, T>::key_iterator::operator!=(key_iterator other) const
1282 Returns \c true if \a other points to a different item than this
1283 iterator; otherwise returns \c false.
1289 \fn template <class Key, class T> QMap<Key, T>::key_iterator &QMap<Key, T>::key_iterator::operator++()
1291 The prefix \c{++} operator (\c{++i}) advances the iterator to the
1292 next item in the hash and returns an iterator to the new current
1295 Calling this function on QMap::keyEnd() leads to undefined results.
1300/*! \fn template <class Key, class T> QMap<Key, T>::key_iterator QMap<Key, T>::key_iterator::operator++(int)
1304 The postfix \c{++} operator (\c{i++}) advances the iterator to the
1305 next item in the hash and returns an iterator to the previous
1309/*! \fn template <class Key, class T> QMap<Key, T>::key_iterator &QMap<Key, T>::key_iterator::operator--()
1311 The prefix \c{--} operator (\c{--i}) makes the preceding item
1312 current and returns an iterator pointing to the new current item.
1314 Calling this function on QMap::keyBegin() leads to undefined
1320/*! \fn template <class Key, class T> QMap<Key, T>::key_iterator QMap<Key, T>::key_iterator::operator--(int)
1324 The postfix \c{--} operator (\c{i--}) makes the preceding item
1325 current and returns an iterator pointing to the previous
1329/*! \fn template <class Key, class T> const_iterator QMap<Key, T>::key_iterator::base() const
1330 Returns the underlying const_iterator this key_iterator is based on.
1333/*! \typedef QMap::const_key_value_iterator
1336 \brief The QMap::const_key_value_iterator typedef provides an STL-style iterator for QMap.
1338 QMap::const_key_value_iterator is essentially the same as QMap::const_iterator
1339 with the difference that operator*() returns a key/value pair instead of a
1342 \sa QKeyValueIterator
1345/*! \typedef QMap::key_value_iterator
1348 \brief The QMap::key_value_iterator typedef provides an STL-style iterator for QMap.
1350 QMap::key_value_iterator is essentially the same as QMap::iterator
1351 with the difference that operator*() returns a key/value pair instead of a
1354 \sa QKeyValueIterator
1357/*! \fn template <class Key, class T> QDataStream &operator<<(QDataStream &out, const QMap<Key, T> &map)
1360 Writes the map \a map to stream \a out.
1362 This function requires the key and value types to implement \c
1365 \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
1368/*! \fn template <class Key, class T> QDataStream &operator>>(QDataStream &in, QMap<Key, T> &map)
1371 Reads a map from stream \a in into \a map.
1373 This function requires the key and value types to implement \c
1376 \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
1379/*! \fn template <typename Key, typename T, typename Predicate> qsizetype erase_if(QMap<Key, T> &map, Predicate pred)
1383 Removes all elements for which the predicate \a pred returns true
1384 from the map \a map.
1386 The function supports predicates which take either an argument of
1387 type \c{QMap<Key, T>::iterator}, or an argument of type
1388 \c{std::pair<const Key &, T &>}.
1390 Returns the number of elements removed, if any.
1394 \fn template <class Key, class T> size_t QMap<Key, T>::qHash(const QMap &key, size_t seed) noexcept
1397 Returns the hash value for \a key, using \a seed to seed the calculation.
1399 Types \c Key and \c T must be supported by qHash().