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