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