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