QMap - add insert overload that provide a hint

This adds a fast insert on QMap when providing a correct hint.

Change-Id: I256bba342932c1d4f24c6e65074e1bf47b519537
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
Reviewed-by: Lars Knoll <lars.knoll@digia.com>

2 files changed, 93 insertions, 0 deletions

diff --git a/src/corelib/tools/qmap.cpp b/src/corelib/tools/qmap.cpp
index a4c28b5bd4..21ac059a01 100644
--- a/src/corelib/tools/qmap.cpp
+++ b/src/corelib/tools/qmap.cpp
@@ -981,6 +981,32 @@ void QMapDataBase::freeData(QMapDataBase *d)
     \sa insertMulti()
 */
 
+/*! \fn QMap::iterator QMap::insert(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 (strictly) 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 key \a key, that item's value
+    is replaced with \a value.
+
+    If there are multiple items with the key \a key, then exactly one of them
+    is replaced with \a value.
+
+    When creating a map from sorted data inserting the largest key first with constBegin()
+    is faster than inserting in sorted order with constEnd()
+
+    \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 insertMulti()
+*/
+
 /*! \fn QMap::iterator QMap::insertMulti(const Key &key, const T &value)
 
     Inserts a new item with the key \a key and a value of \a value.
diff --git a/src/corelib/tools/qmap.h b/src/corelib/tools/qmap.h
index 280696c534..31a891b0c2 100644
--- a/src/corelib/tools/qmap.h
+++ b/src/corelib/tools/qmap.h
@@ -538,6 +538,7 @@ public:
     iterator upperBound(const Key &key);
     const_iterator upperBound(const Key &key) const;
     iterator insert(const Key &key, const T &value);
+    iterator insert(const_iterator pos, const Key &key, const T &value);
     iterator insertMulti(const Key &key, const T &value);
     QMap<Key, T> &unite(const QMap<Key, T> &other);
 
@@ -663,6 +664,72 @@ Q_INLINE_TEMPLATE typename QMap<Key, T>::iterator QMap<Key, T>::insert(const Key
 }
 
 template <class Key, class T>
+typename QMap<Key, T>::iterator QMap<Key, T>::insert(const_iterator pos, const Key &akey, const T &avalue)
+{
+    if (d->ref.isShared())
+        return this->insert(akey, avalue);
+
+    if (pos == constEnd()) {
+        // Hint is that the Node is larger than (or equal to) the largest value.
+        Node *n = static_cast<Node *>(pos.i->left);
+        if (n) {
+            while (n->right)
+                n = static_cast<Node *>(n->right);
+
+            if (!qMapLessThanKey(n->key, akey))
+                return this->insert(akey, avalue); // ignore hint
+            // This can be optimized by checking equal too.
+            // we can overwrite if previous node key is strictly smaller
+            // (or there is no previous node)
+
+            Node *z = d->createNode(akey, avalue, n, false); // insert right most
+            return iterator(z);
+        }
+        return this->insert(akey, avalue);
+    } else {
+        // Hint indicates that the node should be less (or equal to) the hint given
+        // but larger than the previous value.
+        Node *next = const_cast<Node*>(pos.i);
+        if (qMapLessThanKey(next->key, akey))
+            return this->insert(akey, avalue); // ignore hint
+
+        if (pos == constBegin()) {
+            // There is no previous value
+            // Maybe overwrite left most value
+            if (!qMapLessThanKey(akey, next->key)) {
+                next->value = avalue; // overwrite current iterator
+                return iterator(next);
+            }
+            // insert left most.
+            Node *z = d->createNode(akey, avalue, begin().i, true);
+            return iterator(z);
+        } else {
+            Node *prev = const_cast<Node*>(pos.i->previousNode());
+            if (!qMapLessThanKey(prev->key, akey)) {
+                return this->insert(akey, avalue); // ignore hint
+            }
+            // Hint is ok
+            if (!qMapLessThanKey(akey, next->key)) {
+                next->value = avalue; // overwrite current iterator
+                return iterator(next);
+            }
+
+            // we need to insert (not overwrite)
+            if (prev->right == 0) {
+                Node *z = d->createNode(akey, avalue, prev, false);
+                return iterator(z);
+            }
+            if (next->left == 0) {
+                Node *z = d->createNode(akey, avalue, next, true);
+                return iterator(z);
+            }
+            Q_ASSERT(false); // We should have prev->right == 0 or next->left == 0.
+            return this->insert(akey, avalue);
+        }
+    }
+}
+
+template <class Key, class T>
 Q_INLINE_TEMPLATE typename QMap<Key, T>::iterator QMap<Key, T>::insertMulti(const Key &akey,
                                                                             const T &avalue)
 {