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