QMap - add multiInsert with hint

This provides a fast multiInsert in QMap (and a fast insert in
QMultiMap) when providing a correct hint.

Change-Id: I3c864c3a7842765fe63f8ecb4b54d0e8c9fd22d7
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

1 files changed, 37 insertions, 0 deletions

diff --git a/src/corelib/tools/qmap.cpp b/src/corelib/tools/qmap.cpp
index 21ac059a01..e5de4a1bfd 100644
--- a/src/corelib/tools/qmap.cpp
+++ b/src/corelib/tools/qmap.cpp
@@ -1019,6 +1019,26 @@ void QMapDataBase::freeData(QMapDataBase *d)
     \sa insert(), values()
 */
 
+/*! \fn QMap::iterator QMap::insertMulti(const_iterator pos, const Key &key, const T &value)
+    \overload
+    \since 5.1
+    Inserts a new item with the key \a key and value \a value and with hint \a pos
+    suggesting where to do the insert.
+
+    If constBegin() is used as hint it indicates that the \a key is less than any key in the map
+    while constEnd() suggests that the \a key is larger than any key in the map.
+    Otherwise the hint should meet the condition (\a pos - 1).key() < \a key <= pos.key().
+    If the hint \a pos is wrong it is ignored and a regular insertMulti is done.
+
+    If there is already an item with the same key in the map, this function will simply create a new one.
+
+    \b {Note:} Be careful with the hint. Providing an iterator from an older shared instance might
+    crash but there is also a risk that it will silently corrupt both the map and the \a pos map.
+
+    \sa insert()
+*/
+
+
 /*! \fn QMap<Key, T> &QMap::unite(const QMap<Key, T> &other)
 
     Inserts all the items in the \a other map into this map. If a
@@ -1655,6 +1675,23 @@ void QMapDataBase::freeData(QMapDataBase *d)
     \sa replace()
 */
 
+/*! \fn QMultiMap::iterator QMultiMap::insert(QMap<Key, T>::const_iterator pos, const Key &key, const T &value)
+
+    \since 5.1
+    Inserts a new item with the key \a key and value \a value and with hint \a pos
+    suggesting where to do the insert.
+
+    If constBegin() is used as hint it indicates that the \a key is less than any key in the map
+    while constEnd() suggests that the \a key is larger than any key in the map.
+    Otherwise the hint should meet the condition (\a pos - 1).key() < \a key <= pos.key().
+    If the hint \a pos is wrong it is ignored and a regular insert is done.
+
+    If there is already an item with the same key in the map, this function will simply create a new one.
+
+    \b {Note:} Be careful with the hint. Providing an iterator from an older shared instance might
+    crash but there is also a risk that it will silently corrupt both the map and the \a pos map.
+*/
+
 /*! \fn QMultiMap &QMultiMap::operator+=(const QMultiMap &other)
 
     Inserts all the items in the \a other map into this map and