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