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