Qt 6.x
The Qt SDK
Loading...
Searching...
No Matches
qmultimap.qdoc
Go to the documentation of this file.
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) 2020 The Qt Company Ltd.
3// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
4
5/*!
6 \class QMultiMap
7 \inmodule QtCore
8 \brief The QMultiMap class is a template class that provides an associative array with multiple equivalent keys.
9
10 \ingroup tools
11 \ingroup shared
12
13 \reentrant
14
15 QMultiMap<Key, T> is one of Qt's generic \l{container classes}. It
16 stores (key, value) pairs and provides fast lookup by key.
17
18 QMultiMap and QMultiHash provide very similar functionality. The
19 differences are:
20
21 \list
22 \li QMultiHash provides average faster lookups than QMultiMap. (See \l{Algorithmic
23 Complexity} for details.)
24 \li When iterating over a QMultiHash, the items are arbitrarily ordered.
25 With QMultiMap, the items are always sorted by key.
26 \li The key type of a QMultiHash must provide operator==() and a global
27 qHash(Key) function. The key type of a QMultiMap 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.
31 \endlist
32
33 Here's an example QMultiMap with QString keys and \c int values:
34 \snippet code/src_corelib_tools_qmultimap.cpp 0
35
36 To insert a (key, value) pair into the multi map, you can use insert():
37
38 \snippet code/src_corelib_tools_qmultimap.cpp 2
39
40 This inserts the following three (key, value) pairs into the
41 QMultiMap: ("a", 1), ("b", 3), ("c", 7), and ("c", -5); note
42 that duplicate keys are allowed.
43
44 To look up a value, use find() or value():
45
46 \snippet code/src_corelib_tools_qmultimap.cpp 3
47
48 If there is no item with the specified key in the map, these
49 functions return a \l{default-constructed value}.
50
51 If you want to check whether the map contains a certain key, use
52 contains():
53
54 \snippet code/src_corelib_tools_qmultimap.cpp 4
55
56 There is also a value() overload that uses its second argument as
57 a default value if there is no item with the specified key:
58
59 \snippet code/src_corelib_tools_qmultimap.cpp 5
60
61 If you want to navigate through all the (key, value) pairs stored
62 in a QMultiMap, you can use an iterator. QMultiMap provides both
63 \l{Java-style iterators} (QMultiMapIterator and QMutableMultiMapIterator)
64 and \l{STL-style iterators} (QMultiMap::const_iterator and
65 QMultiMap::iterator). Here's how to iterate over a QMultiMap<QString, int>
66 using a Java-style iterator:
67
68 \snippet code/src_corelib_tools_qmultimap.cpp 7
69
70 Here's the same code, but using an STL-style iterator this time:
71
72 \snippet code/src_corelib_tools_qmultimap.cpp 8
73
74 The items are traversed in ascending key order.
75
76 A QMultiMap allows multiple values per key. If you call
77 insert() with a key that already exists in the map, a
78 new (key, value) pair will be inserted. For example:
79
80 \snippet code/src_corelib_tools_qmultimap.cpp 9
81
82 If you want to retrieve all the values for a single key, you can
83 use values(const Key &key), which returns a QList<T>:
84
85 \snippet code/src_corelib_tools_qmultimap.cpp 10
86
87 The items that share the same key are available from most
88 recently to least recently inserted. Another approach is to call
89 find() to get the STL-style iterator for the first item with a
90 key and iterate from there:
91
92 \snippet code/src_corelib_tools_qmultimap.cpp 11
93
94 If you only need to extract the values from a map (not the keys),
95 you can also use range-based for:
96
97 \snippet code/src_corelib_tools_qmultimap.cpp 12
98
99 Items can be removed from the multi map in several ways. One way is to
100 call remove(); this will remove any item with the given key.
101 Another way is to use QMutableMultiMapIterator::remove(). In addition,
102 you can clear the entire map using clear().
103
104 It is possible to merge two multi maps by calling unite(), by
105 using operator+(), and by using operator+=(). Example:
106
107 \snippet code/src_corelib_tools_qmultimap.cpp 25
108
109 QMultiMap'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, QMultiMap'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 equal if neither \c{x
115 < y} nor \c{y < x} is true.
116
117 Example:
118 \snippet code/src_corelib_tools_qmultimap.cpp 13
119
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.
122
123 \sa QMultiMapIterator, QMutableMultiMapIterator, QMultiHash
124*/
125
126/*! \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap()
127
128 Constructs an empty multi map.
129
130 \sa clear()
131*/
132
133/*!
134 \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap(QMultiMap<Key, T> &&other)
135
136 Move-constructs a QMultiMap instance, making it point at the same
137 object that \a other was pointing to.
138
139 \since 5.2
140*/
141
142/*! \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap(const QMultiMap<Key, T> &other)
143
144 Constructs a copy of \a other.
145
146 This operation occurs in \l{constant time}, because QMultiMap is
147 \l{implicitly shared}. This makes returning a QMultiMap from a
148 function very fast. If a shared instance is modified, it will be
149 copied (copy-on-write), and this takes \l{linear time}.
150
151 \sa operator=()
152*/
153
154/*! \fn template <class Key, class T> QMultiMap<Key, T> &QMultiMap<Key, T>::operator=(const QMultiMap<Key, T> &other)
155
156 Assigns \a other to this multi map and returns a reference to this multi map.
157*/
158
159/*!
160 \fn template <class Key, class T> QMultiMap<Key, T> &QMultiMap<Key, T>::operator=(QMultiMap<Key, T> &&other)
161
162 Move-assigns \a other to this QMultiMap instance.
163
164 \since 5.2
165*/
166
167/*! \fn template <class Key, class T> QMultiMap<Key, T>::~QMultiMap()
168
169 Destroys the multi map. References to the values in the multi map, and all
170 iterators over this multi map, become invalid.
171*/
172
173/*! \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap(std::initializer_list<std::pair<Key,T> > list)
174 \since 5.1
175
176 Constructs a multi map with a copy of each of the elements in the
177 initializer list \a list.
178*/
179
180/*! \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap(const QMap<Key, T> &other)
181 \since 6.0
182
183 Constructs a multi map as a copy of \a other.
184*/
185
186/*! \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap(QMap<Key, T> &&other)
187 \since 6.0
188
189 If \a other is shared, constructs a multi map as a copy of \a other.
190 Otherwise, constructs a multi map by moving the elements from \a other.
191*/
192
193/*! \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap(const std::multimap<Key, T> &other)
194
195 Constructs a copy of \a other.
196
197 \sa toStdMultiMap()
198*/
199
200/*! \fn template <class Key, class T> QMultiMap<Key, T>::QMultiMap(std::multimap<Key, T> &&other)
201
202 Constructs a multi map by moving from \a other.
203
204 \sa toStdMultiMap()
205*/
206
207/*! \fn template <class Key, class T> std::multimap<Key, T> QMultiMap<Key, T>::toStdMap() const
208 \deprecated Use toStdMultiMap() instead.
209
210 Returns an STL multi map equivalent to this QMultiMap.
211*/
212
213/*! \fn template <class Key, class T> std::multimap<Key, T> QMultiMap<Key, T>::toStdMultiMap() const &
214
215 Returns an STL multi map equivalent to this QMultiMap.
216*/
217
218/*! \fn template <class Key, class T> void QMultiMap<Key, T>::swap(QMultiMap<Key, T> &other)
219 \since 4.8
220
221 Swaps multi map \a other with this multi map. This operation is very
222 fast and never fails.
223*/
224
225/*! \fn template<class Key, class T> bool QMultiMap<Key, T>::operator==(const QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
226
227 Returns \c true if \a lhs is equal to \a rhs; otherwise returns
228 false.
229
230 Two multi maps are considered equal if they contain the same (key,
231 value) pairs, in the same order (which matters for duplicate keys).
232
233 This function requires the key and the value types to implement \c
234 operator==().
235
236 \sa operator!=()
237*/
238
239/*! \fn template<class Key, class T> bool QMultiMap<Key, T>::operator!=(const QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
240
241 Returns \c true if \a lhs is not equal to \a rhs; otherwise
242 returns \c false.
243
244 Two multi maps are considered equal if they contain the same (key,
245 value) pairs, in the same order (which matters for duplicate keys).
246
247 This function requires the key and the value types to implement \c
248 operator==().
249
250 \sa operator==()
251*/
252
253/*! \fn template <class Key, class T> qsizetype QMultiMap<Key, T>::size() const
254
255 Returns the number of (key, value) pairs in the multi map.
256
257 \sa isEmpty(), count()
258*/
259
260/*!
261 \fn template <class Key, class T> bool QMultiMap<Key, T>::isEmpty() const
262
263 Returns \c true if the multi map contains no items; otherwise returns
264 false.
265
266 \sa size()
267*/
268
269/*! \fn template <class Key, class T> void QMultiMap<Key, T>::detach()
270
271 \internal
272
273 Detaches this map from any other multi maps with which it may share
274 data.
275
276 \sa isDetached()
277*/
278
279/*! \fn template <class Key, class T> bool QMultiMap<Key, T>::isDetached() const
280
281 \internal
282
283 Returns \c true if the multi map's internal data isn't shared with any
284 other map object; otherwise returns \c false.
285
286 \sa detach()
287*/
288
289/*! \fn template <class Key, class T> bool QMultiMap<Key, T>::isSharedWith(const QMultiMap<Key, T> &other) const
290
291 \internal
292*/
293
294/*! \fn template <class Key, class T> void QMultiMap<Key, T>::clear()
295
296 Removes all items from the multi map.
297
298 \sa remove()
299*/
300
301/*! \fn template <class Key, class T> qsizetype QMultiMap<Key, T>::remove(const Key &key)
302
303 Removes all the items that have the key \a key from the multi map.
304 Returns the number of items removed.
305
306 \sa clear(), take()
307*/
308
309/*! \fn template <class Key, class T> qsizetype QMultiMap<Key, T>::remove(const Key &key, const T &value)
310
311 Removes all the items that have the key \a key and value \a value
312 from the multi map.
313 Returns the number of items removed.
314
315 \sa clear(), take()
316*/
317
318/*! \fn template <class Key, class T> template <typename Predicate> size_type QMultiMap<Key, T>::removeIf(Predicate pred)
319 \since 6.1
320
321 Removes all elements for which the predicate \a pred returns true
322 from the multi map.
323
324 The function supports predicates which take either an argument of
325 type \c{QMultiMap<Key, T>::iterator}, or an argument of type
326 \c{std::pair<const Key &, T &>}.
327
328 Returns the number of elements removed, if any.
329
330 \sa clear(), take()
331*/
332
333/*! \fn template <class Key, class T> T QMultiMap<Key, T>::take(const Key &key)
334
335 Removes the item with the key \a key from the multi map and returns
336 the value associated with it.
337
338 If the item does not exist in the multi map, the function simply
339 returns a \l{default-constructed value}. If there are multiple
340 items for \a key in the map, only the most recently inserted one
341 is removed and returned.
342
343 If you don't use the return value, remove() is more efficient.
344
345 \sa remove()
346*/
347
348/*! \fn template <class Key, class T> bool QMultiMap<Key, T>::contains(const Key &key) const
349
350 Returns \c true if the multi map contains an item with key \a key;
351 otherwise returns \c false.
352
353 \sa count()
354*/
355
356/*! \fn template <class Key, class T> bool QMultiMap<Key, T>::contains(const Key &key, const T &value) const
357 \since 4.3
358
359 Returns \c true if the multi map contains an item with key \a key
360 and value \a value; otherwise returns \c false.
361
362 \sa count()
363*/
364
365/*!
366 \fn template <class Key, class T> Key QMultiMap<Key, T>::key(const T &value, const Key &defaultKey) const
367 \since 4.3
368 \overload
369
370 Returns the first key with value \a value, or \a defaultKey if
371 the multi map contains no item with value \a value. If no \a defaultKey
372 is provided the function returns a
373 \l{default-constructed value}{default-constructed key}.
374
375 This function can be slow (\l{linear time}), because QMultiMap's
376 internal data structure is optimized for fast lookup by key, not
377 by value.
378
379 \sa value(), keys()
380*/
381
382/*! \fn template <class Key, class T> T QMultiMap<Key, T>::value(const Key &key, const T &defaultValue) const
383
384 Returns the value associated with the key \a key.
385
386 If the multi map contains no item with key \a key, the function returns
387 \a defaultValue. If no \a defaultValue is specified, the function
388 returns a \l{default-constructed value}. If there are multiple
389 items for \a key in the multi map, the value of the most recently
390 inserted one is returned.
391
392 \sa key(), values(), contains()
393*/
394
395/*! \fn template <class Key, class T> QList<Key> QMultiMap<Key, T>::keys() const
396
397 Returns a list containing all the keys in the multi map in ascending
398 order. Keys that occur multiple times in the multi map
399 also occur multiple times in the list.
400
401 The order is guaranteed to be the same as that used by values().
402
403 This function creates a new list, in \l {linear time}. The time and memory
404 use that entails can be avoided by iterating from \l keyBegin() to
405 \l keyEnd().
406
407 \sa values(), key()
408*/
409
410/*! \fn template <class Key, class T> QList<Key> QMultiMap<Key, T>::keys(const T &value) const
411
412 \overload
413
414 Returns a list containing all the keys associated with value \a
415 value in ascending order.
416
417 This function can be slow (\l{linear time}), because QMultiMap's
418 internal data structure is optimized for fast lookup by key, not
419 by value.
420*/
421
422/*! \fn template <class Key, class T> QList<Key> QMultiMap<Key, T>::uniqueKeys() const
423 \since 4.2
424
425 Returns a list containing all the keys in the map in ascending
426 order. Keys that occur multiple times in the map occur only
427 once in the returned list.
428*/
429
430/*! \fn template <class Key, class T> QList<T> QMultiMap<Key, T>::values() const
431
432 Returns a list containing all the values in the map, in ascending
433 order of their keys. If a key is associated with multiple values,
434 all of its values will be in the list, and not just the most
435 recently inserted one.
436
437 \sa keys(), value()
438*/
439
440/*! \fn template <class Key, class T> QList<T> QMultiMap<Key, T>::values(const Key &key) const
441
442 Returns a list containing all the values associated with key
443 \a key, from the most recently inserted to the least recently
444 inserted one.
445
446 \sa keys(), value()
447*/
448
449/*! \fn template <class Key, class T> qsizetype QMultiMap<Key, T>::count() const
450
451 \overload
452
453 Same as size().
454*/
455
456/*! \fn template <class Key, class T> qsizetype QMultiMap<Key, T>::count(const Key &key) const
457
458 Returns the number of items associated with key \a key.
459
460 \sa contains(), QMultiMap::count()
461*/
462
463/*! \fn template <class Key, class T> qsizetype QMultiMap<Key, T>::count(const Key &key, const T &value) const
464
465 Returns the number of items with key \a key and value \a value.
466
467 \sa contains(), QMultiMap::count()
468*/
469
470
471/*! \fn template <class Key, class T> const Key &QMultiMap<Key, T>::firstKey() const
472 \since 5.2
473
474 Returns a reference to the smallest key in the multi map.
475 This function assumes that the multi map is not empty.
476
477 This executes in \l{constant time}.
478
479 \sa lastKey(), first(), keyBegin(), isEmpty()
480*/
481
482/*! \fn template <class Key, class T> const Key &QMultiMap<Key, T>::lastKey() const
483 \since 5.2
484
485 Returns a reference to the largest key in the multi map.
486 This function assumes that the multi map is not empty.
487
488 This executes in \l{logarithmic time}.
489
490 \sa firstKey(), last(), keyEnd(), isEmpty()
491*/
492
493/*! \fn template <class Key, class T> T &QMultiMap<Key, T>::first()
494 \since 5.2
495
496 Returns a reference to the first value in the multi map, that is the value mapped
497 to the smallest key. This function assumes that the multi map is not empty.
498
499 When unshared (or const version is called), this executes in \l{constant time}.
500
501 \sa last(), firstKey(), isEmpty()
502*/
503
504/*! \fn template <class Key, class T> const T &QMultiMap<Key, T>::first() const
505 \since 5.2
506
507 \overload
508*/
509
510/*! \fn template <class Key, class T> T &QMultiMap<Key, T>::last()
511 \since 5.2
512
513 Returns a reference to the last value in the multi map, that is the value mapped
514 to the largest key. This function assumes that the map is not empty.
515
516 When unshared (or const version is called), this executes in \l{logarithmic time}.
517
518 \sa first(), lastKey(), isEmpty()
519*/
520
521/*! \fn template <class Key, class T> const T &QMultiMap<Key, T>::last() const
522 \since 5.2
523
524 \overload
525*/
526
527/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::begin()
528
529 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first item in
530 the multi map.
531
532 \sa constBegin(), end()
533*/
534
535/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::begin() const
536
537 \overload
538*/
539
540/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::cbegin() const
541 \since 5.0
542
543 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
544 in the multi map.
545
546 \sa begin(), cend()
547*/
548
549/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::constBegin() const
550
551 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
552 in the multi map.
553
554 \sa begin(), constEnd()
555*/
556
557/*! \fn template <class Key, class T> QMultiMap<Key, T>::key_iterator QMultiMap<Key, T>::keyBegin() const
558 \since 5.6
559
560 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first key
561 in the multi map.
562
563 \sa keyEnd(), firstKey()
564*/
565
566/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::end()
567
568 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary item
569 after the last item in the multi map.
570
571 \sa begin(), constEnd()
572*/
573
574/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::end() const
575
576 \overload
577*/
578
579/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::cend() const
580 \since 5.0
581
582 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
583 item after the last item in the multi map.
584
585 \sa cbegin(), end()
586*/
587
588/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::constEnd() const
589
590 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
591 item after the last item in the multi map.
592
593 \sa constBegin(), end()
594*/
595
596/*! \fn template <class Key, class T> QMultiMap<Key, T>::key_iterator QMultiMap<Key, T>::keyEnd() const
597 \since 5.6
598
599 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
600 item after the last key in the multi map.
601
602 \sa keyBegin(), lastKey()
603*/
604
605
606/*! \fn template <class Key, class T> QMultiMap<Key, T>::key_value_iterator QMultiMap<Key, T>::keyValueBegin()
607 \since 5.10
608
609 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first entry
610 in the multi map.
611
612 \sa keyValueEnd()
613*/
614
615/*! \fn template <class Key, class T> QMultiMap<Key, T>::key_value_iterator QMultiMap<Key, T>::keyValueEnd()
616 \since 5.10
617
618 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
619 entry after the last entry in the multi map.
620
621 \sa keyValueBegin()
622*/
623
624/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_key_value_iterator QMultiMap<Key, T>::keyValueBegin() const
625 \since 5.10
626
627 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
628 in the multi map.
629
630 \sa keyValueEnd()
631*/
632
633/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_key_value_iterator QMultiMap<Key, T>::constKeyValueBegin() const
634 \since 5.10
635
636 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
637 in the multi map.
638
639 \sa keyValueBegin()
640*/
641
642/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_key_value_iterator QMultiMap<Key, T>::keyValueEnd() const
643 \since 5.10
644
645 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
646 entry after the last entry in the multi map.
647
648 \sa keyValueBegin()
649*/
650
651/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_key_value_iterator QMultiMap<Key, T>::constKeyValueEnd() const
652 \since 5.10
653
654 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
655 entry after the last entry in the multi map.
656
657 \sa constKeyValueBegin()
658*/
659
660/*! \fn template <class Key, class T> auto QMultiMap<Key, T>::asKeyValueRange() &
661 \fn template <class Key, class T> auto QMultiMap<Key, T>::asKeyValueRange() const &
662 \fn template <class Key, class T> auto QMultiMap<Key, T>::asKeyValueRange() &&
663 \fn template <class Key, class T> auto QMultiMap<Key, T>::asKeyValueRange() const &&
664 \since 6.4
665
666 Returns a range object that allows iteration over this multi map as
667 key/value pairs. For instance, this range object can be used in a
668 range-based for loop, in combination with a structured binding declaration:
669
670 \snippet code/src_corelib_tools_qmultimap.cpp 26
671
672 Note that both the key and the value obtained this way are
673 references to the ones in the multi map. Specifically, mutating the value
674 will modify the map itself.
675
676 \sa QKeyValueIterator
677*/
678
679/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::erase(const_iterator pos)
680
681 Removes the (key, value) pair pointed to by the iterator \a pos
682 from the multi map, and returns an iterator to the next item in the
683 map.
684
685 \note The iterator \a pos must be valid and dereferenceable.
686
687 \sa remove()
688*/
689
690/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::erase(const_iterator first, const_iterator last)
691 \since 6.0
692
693 Removes the (key, value) pairs pointed to by the iterator range
694 [\a first, \a last) from the multi map.
695 Returns an iterator to the item in the multi map following the last
696 removed element.
697
698 \note The range \c {[first, last)} \e must be a valid range in \c {*this}.
699
700 \sa remove()
701*/
702
703/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::find(const Key &key)
704
705 Returns an iterator pointing to the item with key \a key in the
706 multi map.
707
708 If the multi map contains no item with key \a key, the function
709 returns end().
710
711 If the map contains multiple items with key \a key, this
712 function returns an iterator that points to the most recently
713 inserted value. The other values are accessible by incrementing
714 the iterator. For example, here's some code that iterates over all
715 the items with the same key:
716
717 \snippet code/src_corelib_tools_qmultimap.cpp 11
718
719 \sa constFind(), value(), values(), lowerBound(), upperBound()
720*/
721
722/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::find(const Key &key) const
723
724 \overload
725*/
726
727/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::constFind(const Key &key) const
728 \since 4.1
729
730 Returns an const iterator pointing to the item with key \a key in the
731 multi map.
732
733 If the multi map contains no item with key \a key, the function
734 returns constEnd().
735
736 \sa find(), QMultiMap::constFind()
737*/
738
739/*!
740 \fn template <class Key, class T> typename QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::find(const Key &key, const T &value) const
741 \since 4.3
742 \overload
743
744 Returns a const iterator pointing to the item with the given \a key and
745 \a value in the map.
746
747 If the map contains no such item, the function returns end().
748
749 If the map contains multiple items with the specified \a key, this
750 function returns a const iterator that points to the most recently
751 inserted value.
752*/
753
754/*!
755 \fn template <class Key, class T> typename QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::constFind(const Key &key, const T &value) const
756 \since 4.3
757
758 Returns an iterator pointing to the item with key \a key and the
759 value \a value in the map.
760
761 If the map contains no such item, the function returns
762 constEnd().
763
764 \sa QMap::constFind()
765*/
766
767/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::lowerBound(const Key &key)
768
769 Returns an iterator pointing to the first item with key \a key in
770 the map. If the map contains no item with key \a key, the
771 function returns an iterator to the nearest item with a greater
772 key.
773
774 Example:
775 \snippet code/src_corelib_tools_qmultimap.cpp 15
776
777 If the map contains multiple items with key \a key, this
778 function returns an iterator that points to the most recently
779 inserted value. The other values are accessible by incrementing
780 the iterator. For example, here's some code that iterates over all
781 the items with the same key:
782
783 \snippet code/src_corelib_tools_qmultimap.cpp 16
784
785 \sa upperBound(), find()
786*/
787
788/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::lowerBound(const Key &key) const
789
790 \overload
791*/
792
793/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::upperBound(const Key &key)
794
795 Returns an iterator pointing to the item that immediately follows
796 the last item with key \a key in the map. If the map contains no
797 item with key \a key, the function returns an iterator to the
798 nearest item with a greater key.
799
800 Example:
801 \snippet code/src_corelib_tools_qmultimap.cpp 17
802
803 \sa lowerBound(), find()
804*/
805
806/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::upperBound(const Key &key) const
807
808 \overload
809*/
810
811/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insert(const Key &key, const T &value)
812
813 Inserts a new item with the key \a key and a value of \a value.
814
815 If there is already an item with the same key in the map, this
816 function will simply create a new one. (This behavior is
817 different from replace(), which overwrites the value of an
818 existing item.)
819
820 \sa replace()
821*/
822
823/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insert(const_iterator pos, const Key &key, const T &value)
824 \overload
825 \since 5.1
826 Inserts a new item with the key \a key and value \a value and with hint \a pos
827 suggesting where to do the insert.
828
829 If constBegin() is used as hint it indicates that the \a key is less than any key in the multi map
830 while constEnd() suggests that the \a key is (strictly) larger than any key in the multi map.
831 Otherwise the hint should meet the condition (\a pos - 1).key() < \a key <= pos.key().
832 If the hint \a pos is wrong it is ignored and a regular insert is done.
833
834 If the hint is correct and the multi map is unshared, the insert executes in amortized \l{constant time}.
835
836 If there is already an item with the same key in the map, this function will simply create a new one.
837
838 When creating a multi map from sorted data inserting the largest key first with constBegin()
839 is faster than inserting in sorted order with constEnd(), since constEnd() - 1 (which is needed
840 to check if the hint is valid) needs \l{logarithmic time}.
841
842 \b {Note:} Be careful with the hint. Providing an iterator from an older shared instance might
843 crash but there is also a risk that it will silently corrupt both the multi map and the \a pos multi map.
844*/
845
846#if QT_DEPRECATED_SINCE(6, 0)
847/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insertMulti(const Key &key, const T &value)
848 \deprecated Use insert() instead.
849
850 Inserts a new item with the key \a key and a value of \a value, and returns an iterator pointing to the new item.
851*/
852
853/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insertMulti(const_iterator pos, const Key &key, const T &value)
854 \deprecated Use insert() instead.
855 \overload
856
857 Inserts a new item with the key \a key and value \a value and with hint \a pos
858 suggesting where to do the insert.
859*/
860
861/*! \fn template <class Key, class T> void QMultiMap<Key, T>::insert(const QMultiMap<Key, T> &map)
862 \since 5.15
863 \deprecated Use unite() instead.
864
865 Inserts all the items in \a map into this map.
866*/
867
868/*! \fn template <class Key, class T> void QMultiMap<Key, T>::insert(QMultiMap<Key, T> &&map)
869 \since 5.15
870 \deprecated Use unite() instead.
871 \overload
872
873 Moves all the items from \a map into this map.
874
875 If \a map is shared, then the items will be copied instead.
876*/
877#endif
878
879/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::replace(const Key &key, const T &value)
880
881 Inserts a new item with the key \a key and a value of \a value.
882
883 If there is already an item with the key \a key, that item's value
884 is replaced with \a value.
885
886 If there are multiple items with the key \a key, the most
887 recently inserted item's value is replaced with \a value.
888
889 \sa insert()
890*/
891
892/*! \typedef QMultiMap::Iterator
893
894 Qt-style synonym for QMultiMap::iterator.
895*/
896
897/*! \typedef QMultiMap::ConstIterator
898
899 Qt-style synonym for QMultiMap::const_iterator.
900*/
901
902/*! \typedef QMultiMap::difference_type
903
904 Typedef for ptrdiff_t. Provided for STL compatibility.
905*/
906
907/*! \typedef QMultiMap::key_type
908
909 Typedef for Key. Provided for STL compatibility.
910*/
911
912/*! \typedef QMultiMap::mapped_type
913
914 Typedef for T. Provided for STL compatibility.
915*/
916
917/*! \typedef QMultiMap::size_type
918
919 Typedef for int. Provided for STL compatibility.
920*/
921
922/*!
923 \fn template <class Key, class T> bool QMultiMap<Key, T>::empty() const
924
925 This function is provided for STL compatibility. It is equivalent
926 to isEmpty(), returning true if the map is empty; otherwise
927 returning false.
928*/
929
930/*!
931 \fn template <class Key, class T> QPair<typename QMultiMap<Key, T>::iterator, typename QMultiMap<Key, T>::iterator> QMultiMap<Key, T>::equal_range(const Key &key)
932
933 Returns a pair of iterators delimiting the range of values \c{[first, second)}, that
934 are stored under \a key.
935*/
936
937/*!
938 \fn template <class Key, class T> QPair<typename QMultiMap<Key, T>::const_iterator, typename QMultiMap<Key, T>::const_iterator> QMultiMap<Key, T>::equal_range(const Key &key) const
939 \overload
940 \since 5.6
941*/
942
943/*!
944 \fn template <class Key, class T> QMultiMap<Key, T> &QMultiMap<Key, T>::unite(const QMultiMap<Key, T> &other)
945
946 Inserts all the items in the \a other map into this map. If a
947 key is common to both maps, the resulting map will contain the
948 key multiple times.
949*/
950
951/*!
952 \fn template <class Key, class T> QMultiMap<Key, T> &QMultiMap<Key, T>::unite(QMultiMap<Key, T> &&other)
953
954 Moves all the items from the \a other map into this map. If a
955 key is common to both maps, the resulting map will contain the
956 key multiple times.
957
958 If \a other is shared, then the items will be copied instead.
959*/
960
961/*! \fn template <class Key, class T> QMultiMap<Key, T> operator+=(QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
962 \relates QMultiMap
963
964 Inserts all the items in the \a rhs map into the \a lhs map and
965 returns the resulting map.
966
967 \sa insert(), operator+()
968*/
969
970/*! \fn template <class Key, class T> QMultiMap<Key, T> operator+(const QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
971 \relates QMultiMap
972
973 Returns a map that contains all the items in the \a lhs map in
974 addition to all the items in \a rhs. If a key is common to both
975 maps, the resulting map will contain the key multiple times.
976
977 \sa operator+=()
978*/
979
980/*! \class QMultiMap::iterator
981 \inmodule QtCore
982 \brief The QMultiMap::iterator class provides an STL-style non-const iterator for QMultiMap.
983
984 QMultiMap<Key, T>::iterator allows you to iterate over a QMultiMap
985 and to modify the value (but not the key) stored under
986 a particular key. If you want to iterate over a const QMultiMap, you
987 should use QMultiMap::const_iterator. It is generally good practice to
988 use QMultiMap::const_iterator on a non-const QMultiMap as well, unless you
989 need to change the QMultiMap through the iterator. Const iterators are
990 slightly faster, and can improve code readability.
991
992 The default QMultiMap::iterator constructor creates an uninitialized
993 iterator. You must initialize it using a QMultiMap function like
994 QMultiMap::begin(), QMultiMap::end(), or QMultiMap::find() before you can
995 start iterating. Here's a typical loop that prints all the (key,
996 value) pairs stored in a map:
997
998 Unlike QMultiHash, which stores its items in an arbitrary order, QMultiMap
999 stores its items ordered by key. Items that share the same key
1000 will appear consecutively,
1001 from the most recently to the least recently inserted value.
1002
1003 Here's an example that increments every value stored in the QMultiMap
1004 by 2:
1005
1006 \snippet code/src_corelib_tools_qmultimap.cpp 19
1007
1008 To remove elements from a QMultiMap you can use erase_if(QMultiMap<Key, T> &map, Predicate pred):
1009
1010 \snippet code/src_corelib_tools_qmultimap.cpp 21
1011
1012 Multiple iterators can be used on the same map. If you add items
1013 to the map, existing iterators will remain valid. If you remove
1014 items from the map, iterators that point to the removed items
1015 will become dangling iterators.
1016
1017 \warning Iterators on implicitly shared containers do not work
1018 exactly like STL-iterators. You should avoid copying a container
1019 while iterators are active on that container. For more information,
1020 read \l{Implicit sharing iterator problem}.
1021
1022 \sa QMultiMap::const_iterator, QMultiMap::key_iterator, QMultiMap::key_value_iterator
1023*/
1024
1025/*! \typedef QMultiMap::iterator::difference_type
1026
1027 \internal
1028*/
1029
1030/*! \typedef QMultiMap::iterator::iterator_category
1031
1032 A synonym for \e {std::bidirectional_iterator_tag} indicating
1033 this iterator is a bidirectional iterator.
1034*/
1035
1036/*! \typedef QMultiMap::iterator::pointer
1037
1038 \internal
1039*/
1040
1041/*! \typedef QMultiMap::iterator::reference
1042
1043 \internal
1044*/
1045
1046/*! \typedef QMultiMap::iterator::value_type
1047
1048 \internal
1049*/
1050
1051/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator::iterator()
1052
1053 Constructs an uninitialized iterator.
1054
1055 Functions like key(), value(), and operator++() must not be
1056 called on an uninitialized iterator. Use operator=() to assign a
1057 value to it before using it.
1058
1059 \sa QMultiMap::begin(), QMultiMap::end()
1060*/
1061
1062/*! \fn template <class Key, class T> const Key &QMultiMap<Key, T>::iterator::key() const
1063
1064 Returns the current item's key as a const reference.
1065
1066 There is no direct way of changing an item's key through an
1067 iterator, although it can be done by calling QMultiMap::erase()
1068 followed by QMultiMap::insert().
1069
1070 \sa value()
1071*/
1072
1073/*! \fn template <class Key, class T> T &QMultiMap<Key, T>::iterator::value() const
1074
1075 Returns a modifiable reference to the current item's value.
1076
1077 You can change the value of an item by using value() on
1078 the left side of an assignment, for example:
1079
1080 \snippet code/src_corelib_tools_qmultimap.cpp 23
1081
1082 \sa key(), operator*()
1083*/
1084
1085/*! \fn template <class Key, class T> T &QMultiMap<Key, T>::iterator::operator*() const
1086
1087 Returns a modifiable reference to the current item's value.
1088
1089 Same as value().
1090
1091 \sa key()
1092*/
1093
1094/*! \fn template <class Key, class T> T *QMultiMap<Key, T>::iterator::operator->() const
1095
1096 Returns a pointer to the current item's value.
1097
1098 \sa value()
1099*/
1100
1101/*!
1102 \fn template<class Key, class T> bool QMultiMap<Key, T>::iterator::operator==(const iterator &lhs, const iterator &rhs)
1103 \fn template<class Key, class T> bool QMultiMap<Key, T>::const_iterator::operator==(const const_iterator &lhs, const const_iterator &rhs)
1104
1105 Returns \c true if \a lhs points to the same item as the \a rhs iterator;
1106 otherwise returns \c false.
1107
1108 \sa operator!=()
1109*/
1110
1111/*!
1112 \fn template<class Key, class T> bool QMultiMap<Key, T>::iterator::operator!=(const iterator &lhs, const iterator &rhs)
1113 \fn template<class Key, class T> bool QMultiMap<Key, T>::const_iterator::operator!=(const const_iterator &lhs, const const_iterator &rhs)
1114
1115 Returns \c true if \a lhs points to a different item than the \a rhs iterator;
1116 otherwise returns \c false.
1117
1118 \sa operator==()
1119*/
1120
1121/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator &QMultiMap<Key, T>::iterator::operator++()
1122
1123 The prefix \c{++} operator (\c{++i}) advances the iterator to the
1124 next item in the multi map and returns an iterator to the new current
1125 item.
1126
1127 Calling this function on QMultiMap::end() leads to undefined results.
1128
1129 \sa operator--()
1130*/
1131
1132/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator++(int)
1133
1134 \overload
1135
1136 The postfix \c{++} operator (\c{i++}) advances the iterator to the
1137 next item in the multi map and returns an iterator to the previously
1138 current item.
1139*/
1140
1141/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator &QMultiMap<Key, T>::iterator::operator--()
1142
1143 The prefix \c{--} operator (\c{--i}) makes the preceding item
1144 current and returns an iterator pointing to the new current item.
1145
1146 Calling this function on QMultiMap::begin() leads to undefined
1147 results.
1148
1149 \sa operator++()
1150*/
1151
1152/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator--(int)
1153
1154 \overload
1155
1156 The postfix \c{--} operator (\c{i--}) makes the preceding item
1157 current and returns an iterator pointing to the previously
1158 current item.
1159*/
1160
1161/*!
1162 //! friends
1163 \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)
1164 \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)
1165 \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)
1166 \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)
1167
1168 //! members
1169 \fn template <class Key, class T> typename QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator+=(QMultiMap<Key, T>::iterator::difference_type n)
1170 \fn template <class Key, class T> typename QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator-=(QMultiMap<Key, T>::iterator::difference_type n)
1171
1172 \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
1173
1174 Move an iterator by \e{n} positions. These operations can be
1175 expensive for large values of \e{n}; QMultiMap iterators are not
1176 random access.
1177*/
1178
1179/*! \class QMultiMap::const_iterator
1180 \inmodule QtCore
1181 \brief The QMultiMap::const_iterator class provides an STL-style const iterator for QMultiMap.
1182
1183 QMultiMap<Key, T>::const_iterator allows you to iterate over a QMultiMap.
1184 If you want to modify the QMultiMap as you iterate
1185 over it, you must use QMultiMap::iterator instead. It is generally
1186 good practice to use QMultiMap::const_iterator on a non-const QMultiMap as
1187 well, unless you need to change the QMultiMap through the iterator.
1188 Const iterators are slightly faster, and can improve code
1189 readability.
1190
1191 The default QMultiMap::const_iterator constructor creates an
1192 uninitialized iterator. You must initialize it using a QMultiMap
1193 function like QMultiMap::cbegin(), QMultiMap::cend(), or
1194 QMultiMap::constFind() before you can start iterating. Here's a typical
1195 loop that prints all the (key, value) pairs stored in a map:
1196
1197 \snippet code/src_corelib_tools_qmultimap.cpp 24
1198
1199 Here's an example that removes all the items whose value is greater than 10:
1200
1201 \snippet code/src_corelib_tools_qmultimap.cpp 20
1202
1203 Unlike QMultiHash, which stores its items in an arbitrary order, QMultiMap
1204 stores its items ordered by key. Items that share the same key
1205 will appear consecutively,
1206 from the most recently to the least recently inserted value.
1207
1208 Multiple iterators can be used on the same multi map. If you add items
1209 to the map, existing iterators will remain valid. If you remove
1210 items from the map, iterators that point to the removed items
1211 will become dangling iterators.
1212
1213 \warning Iterators on implicitly shared containers do not work
1214 exactly like STL-iterators. You should avoid copying a container
1215 while iterators are active on that container. For more information,
1216 read \l{Implicit sharing iterator problem}.
1217
1218 \sa QMultiMap::iterator, QMultiMap::key_iterator, QMultiMap::const_key_value_iterator
1219*/
1220
1221/*! \typedef QMultiMap::const_iterator::difference_type
1222
1223 \internal
1224*/
1225
1226/*! \typedef QMultiMap::const_iterator::iterator_category
1227
1228 A synonym for \e {std::bidirectional_iterator_tag} indicating
1229 this iterator is a bidirectional iterator.
1230*/
1231
1232/*! \typedef QMultiMap::const_iterator::pointer
1233
1234 \internal
1235*/
1236
1237/*! \typedef QMultiMap::const_iterator::reference
1238
1239 \internal
1240*/
1241
1242/*! \typedef QMultiMap::const_iterator::value_type
1243
1244 \internal
1245*/
1246
1247/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator::const_iterator()
1248
1249 Constructs an uninitialized iterator.
1250
1251 Functions like key(), value(), and operator++() must not be
1252 called on an uninitialized iterator. Use operator=() to assign a
1253 value to it before using it.
1254
1255 \sa QMultiMap::constBegin(), QMultiMap::constEnd()
1256*/
1257
1258/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator::const_iterator(const iterator &other)
1259
1260 Constructs a copy of \a other.
1261*/
1262
1263/*! \fn template <class Key, class T> const Key &QMultiMap<Key, T>::const_iterator::key() const
1264
1265 Returns the current item's key.
1266
1267 \sa value()
1268*/
1269
1270/*! \fn template <class Key, class T> const T &QMultiMap<Key, T>::const_iterator::value() const
1271
1272 Returns the current item's value.
1273
1274 \sa key(), operator*()
1275*/
1276
1277/*! \fn template <class Key, class T> const T &QMultiMap<Key, T>::const_iterator::operator*() const
1278
1279 Returns the current item's value.
1280
1281 Same as value().
1282
1283 \sa key()
1284*/
1285
1286/*! \fn template <class Key, class T> const T *QMultiMap<Key, T>::const_iterator::operator->() const
1287
1288 Returns a pointer to the current item's value.
1289
1290 \sa value()
1291*/
1292
1293/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator &QMultiMap<Key, T>::const_iterator::operator++()
1294
1295 The prefix \c{++} operator (\c{++i}) advances the iterator to the
1296 next item in the map and returns an iterator to the new current
1297 item.
1298
1299 Calling this function on QMultiMap::end() leads to undefined results.
1300
1301 \sa operator--()
1302*/
1303
1304/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator++(int)
1305
1306 \overload
1307
1308 The postfix \c{++} operator (\c{i++}) advances the iterator to the
1309 next item in the map and returns an iterator to the previously
1310 current item.
1311*/
1312
1313/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator &QMultiMap<Key, T>::const_iterator::operator--()
1314
1315 The prefix \c{--} operator (\c{--i}) makes the preceding item
1316 current and returns an iterator pointing to the new current item.
1317
1318 Calling this function on QMultiMap::begin() leads to undefined
1319 results.
1320
1321 \sa operator++()
1322*/
1323
1324/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator--(int)
1325
1326 \overload
1327
1328 The postfix \c{--} operator (\c{i--}) makes the preceding item
1329 current and returns an iterator pointing to the previously
1330 current item.
1331*/
1332
1333/*!
1334 //! friends
1335 \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)
1336 \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)
1337 \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)
1338 \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)
1339
1340 //! members
1341 \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)
1342 \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)
1343
1344 \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
1345
1346 Move an iterator by \e{n} positions. These operations can be
1347 expensive for large values of \e{n}. QMultiMap iterators are not
1348 random access.
1349*/
1350
1351/*! \class QMultiMap::key_iterator
1352 \inmodule QtCore
1353 \since 5.6
1354 \brief The QMultiMap::key_iterator class provides an STL-style const iterator for QMultiMap keys.
1355
1356 QMultiMap::key_iterator is essentially the same as QMultiMap::const_iterator
1357 with the difference that operator*() and operator->() return a key
1358 instead of a value.
1359
1360 For most uses QMultiMap::iterator and QMultiMap::const_iterator should be used,
1361 you can easily access the key by calling QMultiMap::iterator::key():
1362
1363 \snippet code/src_corelib_tools_qmultimap.cpp keyiterator1
1364
1365 However, to have interoperability between QMultiMap's keys and STL-style
1366 algorithms we need an iterator that dereferences to a key instead
1367 of a value. With QMultiMap::key_iterator we can apply an algorithm to a
1368 range of keys without having to call QMultiMap::keys(), which is inefficient
1369 as it costs one QMultiMap iteration and memory allocation to create a temporary
1370 QList.
1371
1372 \snippet code/src_corelib_tools_qmultimap.cpp keyiterator2
1373
1374 QMultiMap::key_iterator is const, it's not possible to modify the key.
1375
1376 The default QMultiMap::key_iterator constructor creates an uninitialized
1377 iterator. You must initialize it using a QMultiMap function like
1378 QMultiMap::keyBegin() or QMultiMap::keyEnd().
1379
1380 \warning Iterators on implicitly shared containers do not work
1381 exactly like STL-iterators. You should avoid copying a container
1382 while iterators are active on that container. For more information,
1383 read \l{Implicit sharing iterator problem}.
1384
1385 \sa QMultiMap::const_iterator, QMultiMap::iterator
1386*/
1387
1388/*! \typedef QMultiMap::key_iterator::difference_type
1389 \internal
1390*/
1391
1392/*! \typedef QMultiMap::key_iterator::iterator_category
1393 \internal
1394*/
1395
1396/*! \typedef QMultiMap::key_iterator::pointer
1397 \internal
1398*/
1399
1400/*! \typedef QMultiMap::key_iterator::reference
1401 \internal
1402*/
1403
1404/*! \typedef QMultiMap::key_iterator::value_type
1405 \internal
1406*/
1407
1408/*! \fn template <class Key, class T> const T &QMultiMap<Key, T>::key_iterator::operator*() const
1409
1410 Returns the current item's key.
1411*/
1412
1413/*! \fn template <class Key, class T> const T *QMultiMap<Key, T>::key_iterator::operator->() const
1414
1415 Returns a pointer to the current item's key.
1416*/
1417
1418/*! \fn template <class Key, class T> bool QMultiMap<Key, T>::key_iterator::operator==(key_iterator other) const
1419
1420 Returns \c true if \a other points to the same item as this
1421 iterator; otherwise returns \c false.
1422
1423 \sa operator!=()
1424*/
1425
1426/*! \fn template <class Key, class T> bool QMultiMap<Key, T>::key_iterator::operator!=(key_iterator other) const
1427
1428 Returns \c true if \a other points to a different item than this
1429 iterator; otherwise returns \c false.
1430
1431 \sa operator==()
1432*/
1433
1434/*!
1435 \fn template <class Key, class T> QMultiMap<Key, T>::key_iterator &QMultiMap<Key, T>::key_iterator::operator++()
1436
1437 The prefix \c{++} operator (\c{++i}) advances the iterator to the
1438 next item in the hash and returns an iterator to the new current
1439 item.
1440
1441 Calling this function on QMultiMap::keyEnd() leads to undefined results.
1442
1443 \sa operator--()
1444*/
1445
1446/*! \fn template <class Key, class T> QMultiMap<Key, T>::key_iterator QMultiMap<Key, T>::key_iterator::operator++(int)
1447
1448 \overload
1449
1450 The postfix \c{++} operator (\c{i++}) advances the iterator to the
1451 next item in the hash and returns an iterator to the previous
1452 item.
1453*/
1454
1455/*! \fn template <class Key, class T> QMultiMap<Key, T>::key_iterator &QMultiMap<Key, T>::key_iterator::operator--()
1456
1457 The prefix \c{--} operator (\c{--i}) makes the preceding item
1458 current and returns an iterator pointing to the new current item.
1459
1460 Calling this function on QMultiMap::keyBegin() leads to undefined
1461 results.
1462
1463 \sa operator++()
1464*/
1465
1466/*! \fn template <class Key, class T> QMultiMap<Key, T>::key_iterator QMultiMap<Key, T>::key_iterator::operator--(int)
1467
1468 \overload
1469
1470 The postfix \c{--} operator (\c{i--}) makes the preceding item
1471 current and returns an iterator pointing to the previous
1472 item.
1473*/
1474
1475/*! \fn template <class Key, class T> const_iterator QMultiMap<Key, T>::key_iterator::base() const
1476 Returns the underlying const_iterator this key_iterator is based on.
1477*/
1478
1479/*! \typedef QMultiMap::const_key_value_iterator
1480 \inmodule QtCore
1481 \since 5.10
1482 \brief The QMultiMap::const_key_value_iterator typedef provides an STL-style iterator for QMultiMap.
1483
1484 QMultiMap::const_key_value_iterator is essentially the same as QMultiMap::const_iterator
1485 with the difference that operator*() returns a key/value pair instead of a
1486 value.
1487
1488 \sa QKeyValueIterator
1489*/
1490
1491/*! \typedef QMultiMap::key_value_iterator
1492 \inmodule QtCore
1493 \since 5.10
1494 \brief The QMultiMap::key_value_iterator typedef provides an STL-style iterator for QMultiMap.
1495
1496 QMultiMap::key_value_iterator is essentially the same as QMultiMap::iterator
1497 with the difference that operator*() returns a key/value pair instead of a
1498 value.
1499
1500 \sa QKeyValueIterator
1501*/
1502
1503/*! \fn template <class Key, class T> QDataStream &operator<<(QDataStream &out, const QMultiMap<Key, T> &map)
1504 \relates QMultiMap
1505
1506 Writes the multi map \a map to stream \a out.
1507
1508 This function requires the key and value types to implement \c
1509 operator<<().
1510
1511 \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
1512*/
1513
1514/*! \fn template <class Key, class T> QDataStream &operator>>(QDataStream &in, QMultiMap<Key, T> &map)
1515 \relates QMultiMap
1516
1517 Reads a map from stream \a in into \a map.
1518
1519 This function requires the key and value types to implement \c
1520 operator>>().
1521
1522 \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
1523*/
1524
1525/*! \fn template <typename Key, typename T, typename Predicate> qsizetype erase_if(QMultiMap<Key, T> &map, Predicate pred)
1526 \relates QMultiMap
1527 \since 6.1
1528
1529 Removes all elements for which the predicate \a pred returns true
1530 from the multi map \a map.
1531
1532 The function supports predicates which take either an argument of
1533 type \c{QMultiMap<Key, T>::iterator}, or an argument of type
1534 \c{std::pair<const Key &, T &>}.
1535
1536 Returns the number of elements removed, if any.
1537*/