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