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