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 QMultiMap allows duplicate keys and stores items in ascending
874 key order. For duplicate keys, the values are stored in reverse
875 insertion order (the most recently inserted value comes first).
876
877 Returns an iterator pointing to the new element.
878
879 \sa replace()
880*/
881
882/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insert(const_iterator pos, const Key &key, const T &value)
883 \overload
884 \since 5.1
885 Inserts a new item with the key \a key and value \a value and with hint \a pos
886 suggesting where to do the insert.
887
888 If constBegin() is used as hint it indicates that the \a key is less than any key in the multi map
889 while constEnd() suggests that the \a key is (strictly) larger than any key in the multi map.
890 Otherwise the hint should meet the condition (\a pos - 1).key() < \a key <= pos.key().
891 If the hint \a pos is wrong it is ignored and a regular insert is done.
892
893 If the hint is correct and the multi map is unshared, the insert executes in amortized \l{constant time}.
894
895 If there is already an item with the same key in the map, this function will simply create a new one.
896
897 When creating a multi map from sorted data inserting the largest key first with constBegin()
898 is faster than inserting in sorted order with constEnd(), since constEnd() - 1 (which is needed
899 to check if the hint is valid) needs \l{logarithmic time}.
900
901 Returns an iterator pointing to the new element.
902
903 \b {Note:} Be careful with the hint. Providing an iterator from an older shared instance might
904 crash but there is also a risk that it will silently corrupt both the multi map and the \a pos multi map.
905*/
906
907#if QT_DEPRECATED_SINCE(6, 0)
908/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insertMulti(const Key &key, const T &value)
909 \deprecated Use insert() instead.
910
911 Inserts a new item with the key \a key and a value of \a value, and returns an iterator pointing to the new item.
912*/
913
914/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insertMulti(const_iterator pos, const Key &key, const T &value)
915 \deprecated Use insert() instead.
916 \overload
917
918 Inserts a new item with the key \a key and value \a value and with hint \a pos
919 suggesting where to do the insert.
920*/
921
922/*! \fn template <class Key, class T> void QMultiMap<Key, T>::insert(const QMultiMap<Key, T> &map)
923 \since 5.15
924 \deprecated Use unite() instead.
925
926 Inserts all the items in \a map into this map.
927*/
928
929/*! \fn template <class Key, class T> void QMultiMap<Key, T>::insert(QMultiMap<Key, T> &&map)
930 \since 5.15
931 \deprecated Use unite() instead.
932 \overload
933
934 Moves all the items from \a map into this map.
935
936 If \a map is shared, then the items will be copied instead.
937*/
938#endif
939
940/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::replace(const Key &key, const T &value)
941
942 Inserts a new item with the key \a key and a value of \a value.
943
944 If there is already an item with the key \a key, that item's value
945 is replaced with \a value.
946
947 If there are multiple items with the key \a key, the most
948 recently inserted item's value is replaced with \a value.
949
950 Returns an iterator pointing to the new/updated element.
951
952 \sa insert()
953*/
954
955/*! \typedef QMultiMap::Iterator
956
957 Qt-style synonym for QMultiMap::iterator.
958*/
959
960/*! \typedef QMultiMap::ConstIterator
961
962 Qt-style synonym for QMultiMap::const_iterator.
963*/
964
965/*! \typedef QMultiMap::difference_type
966
967 Typedef for ptrdiff_t. Provided for STL compatibility.
968*/
969
970/*! \typedef QMultiMap::key_type
971
972 Typedef for Key. Provided for STL compatibility.
973*/
974
975/*! \typedef QMultiMap::mapped_type
976
977 Typedef for T. Provided for STL compatibility.
978*/
979
980/*! \typedef QMultiMap::size_type
981
982 Typedef for int. Provided for STL compatibility.
983*/
984
985/*!
986 \fn template <class Key, class T> bool QMultiMap<Key, T>::empty() const
987
988 This function is provided for STL compatibility. It is equivalent
989 to isEmpty(), returning true if the map is empty; otherwise
990 returning false.
991*/
992
993/*!
994 \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)
995
996 Returns a pair of iterators delimiting the range of values \c{[first, second)}, that
997 are stored under \a key.
998*/
999
1000/*!
1001 \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
1002 \overload
1003 \since 5.6
1004*/
1005
1006/*!
1007 \fn template <class Key, class T> QMultiMap<Key, T> &QMultiMap<Key, T>::unite(const QMultiMap<Key, T> &other)
1008
1009 Inserts all the items in the \a other map into this map. If a
1010 key is common to both maps, the resulting map will contain the
1011 key multiple times.
1012*/
1013
1014/*!
1015 \fn template <class Key, class T> QMultiMap<Key, T> &QMultiMap<Key, T>::unite(QMultiMap<Key, T> &&other)
1016
1017 Moves all the items from the \a other map into this map. If a
1018 key is common to both maps, the resulting map will contain the
1019 key multiple times.
1020
1021 If \a other is shared, then the items will be copied instead.
1022*/
1023
1024/*! \fn template <class Key, class T> QMultiMap<Key, T> operator+=(QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
1025 \relates QMultiMap
1026
1027 Inserts all the items in the \a rhs map into the \a lhs map and
1028 returns the resulting map.
1029
1030 \sa insert(), operator+()
1031*/
1032
1033/*! \fn template <class Key, class T> QMultiMap<Key, T> operator+(const QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
1034 \relates QMultiMap
1035
1036 Returns a map that contains all the items in the \a lhs map in
1037 addition to all the items in \a rhs. If a key is common to both
1038 maps, the resulting map will contain the key multiple times.
1039
1040 \sa operator+=()
1041*/
1042
1043/*! \class QMultiMap::iterator
1044 \inmodule QtCore
1045 \brief The QMultiMap::iterator class provides an STL-style non-const iterator for QMultiMap.
1046
1047 QMultiMap<Key, T>::iterator allows you to iterate over a QMultiMap
1048 and to modify the value (but not the key) stored under
1049 a particular key. If you want to iterate over a const QMultiMap, you
1050 should use QMultiMap::const_iterator. It is generally good practice to
1051 use QMultiMap::const_iterator on a non-const QMultiMap as well, unless you
1052 need to change the QMultiMap through the iterator. Const iterators are
1053 slightly faster, and can improve code readability.
1054
1055 The default QMultiMap::iterator constructor creates an uninitialized
1056 iterator. You must initialize it using a QMultiMap function like
1057 QMultiMap::begin(), QMultiMap::end(), or QMultiMap::find() before you can
1058 start iterating. Here's a typical loop that prints all the (key,
1059 value) pairs stored in a map:
1060
1061 Unlike QMultiHash, which stores its items in an arbitrary order, QMultiMap
1062 stores its items ordered by key. Items that share the same key
1063 will appear consecutively,
1064 from the most recently to the least recently inserted value.
1065
1066 Here's an example that increments every value stored in the QMultiMap
1067 by 2:
1068
1069 \snippet code/src_corelib_tools_qmultimap.cpp 19
1070
1071 To remove elements from a QMultiMap you can use erase_if(QMultiMap<Key, T> &map, Predicate pred):
1072
1073 \snippet code/src_corelib_tools_qmultimap.cpp 21
1074
1075 Multiple iterators can be used on the same map. If you add items
1076 to the map, existing iterators will remain valid. If you remove
1077 items from the map, iterators that point to the removed items
1078 will become dangling iterators.
1079
1080 \warning Iterators on implicitly shared containers do not work
1081 exactly like STL-iterators. You should avoid copying a container
1082 while iterators are active on that container. For more information,
1083 read \l{Implicit sharing iterator problem}.
1084
1085 \sa QMultiMap::const_iterator, QMultiMap::key_iterator, QMultiMap::key_value_iterator
1086*/
1087
1088/*! \typedef QMultiMap::iterator::difference_type
1089
1090 \internal
1091*/
1092
1093/*! \typedef QMultiMap::iterator::iterator_category
1094
1095 A synonym for \e {std::bidirectional_iterator_tag} indicating
1096 this iterator is a bidirectional iterator.
1097*/
1098
1099/*! \typedef QMultiMap::iterator::pointer
1100
1101 \internal
1102*/
1103
1104/*! \typedef QMultiMap::iterator::reference
1105
1106 \internal
1107*/
1108
1109/*! \typedef QMultiMap::iterator::value_type
1110
1111 \internal
1112*/
1113
1114/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator::iterator()
1115
1116 Constructs an uninitialized iterator.
1117
1118 Functions like key(), value(), and operator++() must not be
1119 called on an uninitialized iterator. Use operator=() to assign a
1120 value to it before using it.
1121
1122 \sa QMultiMap::begin(), QMultiMap::end()
1123*/
1124
1125/*! \fn template <class Key, class T> const Key &QMultiMap<Key, T>::iterator::key() const
1126
1127 Returns the current item's key as a const reference.
1128
1129 There is no direct way of changing an item's key through an
1130 iterator, although it can be done by calling QMultiMap::erase()
1131 followed by QMultiMap::insert().
1132
1133 \sa value()
1134*/
1135
1136/*! \fn template <class Key, class T> T &QMultiMap<Key, T>::iterator::value() const
1137
1138 Returns a modifiable reference to the current item's value.
1139
1140 You can change the value of an item by using value() on
1141 the left side of an assignment, for example:
1142
1143 \snippet code/src_corelib_tools_qmultimap.cpp 23
1144
1145 \sa key(), operator*()
1146*/
1147
1148/*! \fn template <class Key, class T> T &QMultiMap<Key, T>::iterator::operator*() const
1149
1150 Returns a modifiable reference to the current item's value.
1151
1152 Same as value().
1153
1154 \sa key()
1155*/
1156
1157/*! \fn template <class Key, class T> T *QMultiMap<Key, T>::iterator::operator->() const
1158
1159 Returns a pointer to the current item's value.
1160
1161 \sa value()
1162*/
1163
1164/*!
1165 \fn template<class Key, class T> bool QMultiMap<Key, T>::iterator::operator==(const iterator &lhs, const iterator &rhs)
1166 \fn template<class Key, class T> bool QMultiMap<Key, T>::const_iterator::operator==(const const_iterator &lhs, const const_iterator &rhs)
1167
1168 Returns \c true if \a lhs points to the same item as the \a rhs iterator;
1169 otherwise returns \c false.
1170
1171 \sa operator!=()
1172*/
1173
1174/*!
1175 \fn template<class Key, class T> bool QMultiMap<Key, T>::iterator::operator!=(const iterator &lhs, const iterator &rhs)
1176 \fn template<class Key, class T> bool QMultiMap<Key, T>::const_iterator::operator!=(const const_iterator &lhs, const const_iterator &rhs)
1177
1178 Returns \c true if \a lhs points to a different item than the \a rhs iterator;
1179 otherwise returns \c false.
1180
1181 \sa operator==()
1182*/
1183
1184/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator &QMultiMap<Key, T>::iterator::operator++()
1185
1186 The prefix \c{++} operator (\c{++i}) advances the iterator to the
1187 next item in the multi map and returns an iterator to the new current
1188 item.
1189
1190 Calling this function on QMultiMap::end() leads to undefined results.
1191
1192 \sa operator--()
1193*/
1194
1195/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator++(int)
1196
1197 \overload
1198
1199 The postfix \c{++} operator (\c{i++}) advances the iterator to the
1200 next item in the multi map and returns an iterator to the previously
1201 current item.
1202*/
1203
1204/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator &QMultiMap<Key, T>::iterator::operator--()
1205
1206 The prefix \c{--} operator (\c{--i}) makes the preceding item
1207 current and returns an iterator pointing to the new current item.
1208
1209 Calling this function on QMultiMap::begin() leads to undefined
1210 results.
1211
1212 \sa operator++()
1213*/
1214
1215/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator--(int)
1216
1217 \overload
1218
1219 The postfix \c{--} operator (\c{i--}) makes the preceding item
1220 current and returns an iterator pointing to the previously
1221 current item.
1222*/
1223
1224/*!
1225 //! friends
1226 \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)
1227 \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)
1228 \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)
1229 \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)
1230
1231 //! members
1232 \fn template <class Key, class T> typename QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator+=(QMultiMap<Key, T>::iterator::difference_type n)
1233 \fn template <class Key, class T> typename QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator-=(QMultiMap<Key, T>::iterator::difference_type n)
1234
1235 \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
1236
1237 Move an iterator by \e{n} positions. These operations can be
1238 expensive for large values of \e{n}; QMultiMap iterators are not
1239 random access.
1240*/
1241
1242/*! \class QMultiMap::const_iterator
1243 \inmodule QtCore
1244 \brief The QMultiMap::const_iterator class provides an STL-style const iterator for QMultiMap.
1245
1246 QMultiMap<Key, T>::const_iterator allows you to iterate over a QMultiMap.
1247 If you want to modify the QMultiMap as you iterate
1248 over it, you must use QMultiMap::iterator instead. It is generally
1249 good practice to use QMultiMap::const_iterator on a non-const QMultiMap as
1250 well, unless you need to change the QMultiMap through the iterator.
1251 Const iterators are slightly faster, and can improve code
1252 readability.
1253
1254 The default QMultiMap::const_iterator constructor creates an
1255 uninitialized iterator. You must initialize it using a QMultiMap
1256 function like QMultiMap::cbegin(), QMultiMap::cend(), or
1257 QMultiMap::constFind() before you can start iterating. Here's a typical
1258 loop that prints all the (key, value) pairs stored in a map:
1259
1260 \snippet code/src_corelib_tools_qmultimap.cpp 24
1261
1262 Here's an example that removes all the items whose value is greater than 10:
1263
1264 \snippet code/src_corelib_tools_qmultimap.cpp 20
1265
1266 Unlike QMultiHash, which stores its items in an arbitrary order, QMultiMap
1267 stores its items ordered by key. Items that share the same key
1268 will appear consecutively,
1269 from the most recently to the least recently inserted value.
1270
1271 Multiple iterators can be used on the same multi map. If you add items
1272 to the map, existing iterators will remain valid. If you remove
1273 items from the map, iterators that point to the removed items
1274 will become dangling iterators.
1275
1276 \warning Iterators on implicitly shared containers do not work
1277 exactly like STL-iterators. You should avoid copying a container
1278 while iterators are active on that container. For more information,
1279 read \l{Implicit sharing iterator problem}.
1280
1281 \sa QMultiMap::iterator, QMultiMap::key_iterator, QMultiMap::const_key_value_iterator
1282*/
1283
1284/*! \typedef QMultiMap::const_iterator::difference_type
1285
1286 \internal
1287*/
1288
1289/*! \typedef QMultiMap::const_iterator::iterator_category
1290
1291 A synonym for \e {std::bidirectional_iterator_tag} indicating
1292 this iterator is a bidirectional iterator.
1293*/
1294
1295/*! \typedef QMultiMap::const_iterator::pointer
1296
1297 \internal
1298*/
1299
1300/*! \typedef QMultiMap::const_iterator::reference
1301
1302 \internal
1303*/
1304
1305/*! \typedef QMultiMap::const_iterator::value_type
1306
1307 \internal
1308*/
1309
1310/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator::const_iterator()
1311
1312 Constructs an uninitialized iterator.
1313
1314 Functions like key(), value(), and operator++() must not be
1315 called on an uninitialized iterator. Use operator=() to assign a
1316 value to it before using it.
1317
1318 \sa QMultiMap::constBegin(), QMultiMap::constEnd()
1319*/
1320
1321/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator::const_iterator(const iterator &other)
1322
1323 Constructs a copy of \a other.
1324*/
1325
1326/*! \fn template <class Key, class T> const Key &QMultiMap<Key, T>::const_iterator::key() const
1327
1328 Returns the current item's key.
1329
1330 \sa value()
1331*/
1332
1333/*! \fn template <class Key, class T> const T &QMultiMap<Key, T>::const_iterator::value() const
1334
1335 Returns the current item's value.
1336
1337 \sa key(), operator*()
1338*/
1339
1340/*! \fn template <class Key, class T> const T &QMultiMap<Key, T>::const_iterator::operator*() const
1341
1342 Returns the current item's value.
1343
1344 Same as value().
1345
1346 \sa key()
1347*/
1348
1349/*! \fn template <class Key, class T> const T *QMultiMap<Key, T>::const_iterator::operator->() const
1350
1351 Returns a pointer to the current item's value.
1352
1353 \sa value()
1354*/
1355
1356/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator &QMultiMap<Key, T>::const_iterator::operator++()
1357
1358 The prefix \c{++} operator (\c{++i}) advances the iterator to the
1359 next item in the map and returns an iterator to the new current
1360 item.
1361
1362 Calling this function on QMultiMap::end() leads to undefined results.
1363
1364 \sa operator--()
1365*/
1366
1367/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator++(int)
1368
1369 \overload
1370
1371 The postfix \c{++} operator (\c{i++}) advances the iterator to the
1372 next item in the map and returns an iterator to the previously
1373 current item.
1374*/
1375
1376/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator &QMultiMap<Key, T>::const_iterator::operator--()
1377
1378 The prefix \c{--} operator (\c{--i}) makes the preceding item
1379 current and returns an iterator pointing to the new current item.
1380
1381 Calling this function on QMultiMap::begin() leads to undefined
1382 results.
1383
1384 \sa operator++()
1385*/
1386
1387/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator--(int)
1388
1389 \overload
1390
1391 The postfix \c{--} operator (\c{i--}) makes the preceding item
1392 current and returns an iterator pointing to the previously
1393 current item.
1394*/
1395
1396/*!
1397 //! friends
1398 \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)
1399 \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)
1400 \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)
1401 \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)
1402
1403 //! members
1404 \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)
1405 \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)
1406
1407 \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
1408
1409 Move an iterator by \e{n} positions. These operations can be
1410 expensive for large values of \e{n}. QMultiMap iterators are not
1411 random access.
1412*/
1413
1414/*! \class QMultiMap::key_iterator
1415 \inmodule QtCore
1416 \since 5.6
1417 \brief The QMultiMap::key_iterator class provides an STL-style const iterator for QMultiMap keys.
1418
1419 QMultiMap::key_iterator is essentially the same as QMultiMap::const_iterator
1420 with the difference that operator*() and operator->() return a key
1421 instead of a value.
1422
1423 For most uses QMultiMap::iterator and QMultiMap::const_iterator should be used,
1424 you can easily access the key by calling QMultiMap::iterator::key():
1425
1426 \snippet code/src_corelib_tools_qmultimap.cpp keyiterator1
1427
1428 However, to have interoperability between QMultiMap's keys and STL-style
1429 algorithms we need an iterator that dereferences to a key instead
1430 of a value. With QMultiMap::key_iterator we can apply an algorithm to a
1431 range of keys without having to call QMultiMap::keys(), which is inefficient
1432 as it costs one QMultiMap iteration and memory allocation to create a temporary
1433 QList.
1434
1435 \snippet code/src_corelib_tools_qmultimap.cpp keyiterator2
1436
1437 QMultiMap::key_iterator is const, it's not possible to modify the key.
1438
1439 The default QMultiMap::key_iterator constructor creates an uninitialized
1440 iterator. You must initialize it using a QMultiMap function like
1441 QMultiMap::keyBegin() or QMultiMap::keyEnd().
1442
1443 \warning Iterators on implicitly shared containers do not work
1444 exactly like STL-iterators. You should avoid copying a container
1445 while iterators are active on that container. For more information,
1446 read \l{Implicit sharing iterator problem}.
1447
1448 \sa QMultiMap::const_iterator, QMultiMap::iterator
1449*/
1450
1451/*! \typedef QMultiMap::key_iterator::difference_type
1452 \internal
1453*/
1454
1455/*! \typedef QMultiMap::key_iterator::iterator_category
1456 \internal
1457*/
1458
1459/*! \typedef QMultiMap::key_iterator::pointer
1460 \internal
1461*/
1462
1463/*! \typedef QMultiMap::key_iterator::reference
1464 \internal
1465*/
1466
1467/*! \typedef QMultiMap::key_iterator::value_type
1468 \internal
1469*/
1470
1471/*! \fn template <class Key, class T> const T &QMultiMap<Key, T>::key_iterator::operator*() const
1472
1473 Returns the current item's key.
1474*/
1475
1476/*! \fn template <class Key, class T> const T *QMultiMap<Key, T>::key_iterator::operator->() const
1477
1478 Returns a pointer to the current item's key.
1479*/
1480
1481/*! \fn template <class Key, class T> bool QMultiMap<Key, T>::key_iterator::operator==(key_iterator other) const
1482
1483 Returns \c true if \a other points to the same item as this
1484 iterator; otherwise returns \c false.
1485
1486 \sa operator!=()
1487*/
1488
1489/*! \fn template <class Key, class T> bool QMultiMap<Key, T>::key_iterator::operator!=(key_iterator other) const
1490
1491 Returns \c true if \a other points to a different item than this
1492 iterator; otherwise returns \c false.
1493
1494 \sa operator==()
1495*/
1496
1497/*!
1498 \fn template <class Key, class T> QMultiMap<Key, T>::key_iterator &QMultiMap<Key, T>::key_iterator::operator++()
1499
1500 The prefix \c{++} operator (\c{++i}) advances the iterator to the
1501 next item in the hash and returns an iterator to the new current
1502 item.
1503
1504 Calling this function on QMultiMap::keyEnd() leads to undefined results.
1505
1506 \sa operator--()
1507*/
1508
1509/*! \fn template <class Key, class T> QMultiMap<Key, T>::key_iterator QMultiMap<Key, T>::key_iterator::operator++(int)
1510
1511 \overload
1512
1513 The postfix \c{++} operator (\c{i++}) advances the iterator to the
1514 next item in the hash and returns an iterator to the previous
1515 item.
1516*/
1517
1518/*! \fn template <class Key, class T> QMultiMap<Key, T>::key_iterator &QMultiMap<Key, T>::key_iterator::operator--()
1519
1520 The prefix \c{--} operator (\c{--i}) makes the preceding item
1521 current and returns an iterator pointing to the new current item.
1522
1523 Calling this function on QMultiMap::keyBegin() leads to undefined
1524 results.
1525
1526 \sa operator++()
1527*/
1528
1529/*! \fn template <class Key, class T> QMultiMap<Key, T>::key_iterator QMultiMap<Key, T>::key_iterator::operator--(int)
1530
1531 \overload
1532
1533 The postfix \c{--} operator (\c{i--}) makes the preceding item
1534 current and returns an iterator pointing to the previous
1535 item.
1536*/
1537
1538/*! \fn template <class Key, class T> const_iterator QMultiMap<Key, T>::key_iterator::base() const
1539 Returns the underlying const_iterator this key_iterator is based on.
1540*/
1541
1542/*! \typedef QMultiMap::const_key_value_iterator
1543 \inmodule QtCore
1544 \since 5.10
1545 \brief The QMultiMap::const_key_value_iterator typedef provides an STL-style iterator for QMultiMap.
1546
1547 QMultiMap::const_key_value_iterator is essentially the same as QMultiMap::const_iterator
1548 with the difference that operator*() returns a key/value pair instead of a
1549 value.
1550
1551 \sa QKeyValueIterator
1552*/
1553
1554/*! \typedef QMultiMap::key_value_iterator
1555 \inmodule QtCore
1556 \since 5.10
1557 \brief The QMultiMap::key_value_iterator typedef provides an STL-style iterator for QMultiMap.
1558
1559 QMultiMap::key_value_iterator is essentially the same as QMultiMap::iterator
1560 with the difference that operator*() returns a key/value pair instead of a
1561 value.
1562
1563 \sa QKeyValueIterator
1564*/
1565
1566/*! \fn template <class Key, class T> QDataStream &operator<<(QDataStream &out, const QMultiMap<Key, T> &map)
1567 \relates QMultiMap
1568
1569 Writes the multi map \a map to stream \a out.
1570
1571 This function requires the key and value types to implement \c
1572 operator<<().
1573
1574 \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
1575*/
1576
1577/*! \fn template <class Key, class T> QDataStream &operator>>(QDataStream &in, QMultiMap<Key, T> &map)
1578 \relates QMultiMap
1579
1580 Reads a map from stream \a in into \a map.
1581
1582 This function requires the key and value types to implement \c
1583 operator>>().
1584
1585 \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
1586*/
1587
1588/*! \fn template <typename Key, typename T, typename Predicate> qsizetype erase_if(QMultiMap<Key, T> &map, Predicate pred)
1589 \relates QMultiMap
1590 \since 6.1
1591
1592 Removes all elements for which the predicate \a pred returns true
1593 from the multi map \a map.
1594
1595 The function supports predicates which take either an argument of
1596 type \c{QMultiMap<Key, T>::iterator}, or an argument of type
1597 \c{std::pair<const Key &, T &>}.
1598
1599 Returns the number of elements removed, if any.
1600*/