Consistenly deprecate QMultiMap insert, add moving unite overload

Change-Id: I8d1d30f3962b0444c27591bf45b6b3c538172039
Reviewed-by: Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>

src/corelib/tools/qmap.h

@@ -1333,29 +1333,13 @@ public:
     {
         unite(map);
     }
-#endif
 
+    QT_DEPRECATED_VERSION_X_6_0("Use unite() instead")
     void insert(QMultiMap<Key, T> &&map)
     {
-        if (!map.d || map.d->m.empty())
-            return;
-
-        if (map.d.isShared()) {
-            // fall back to a regular copy
-            insert(map);
-            return;
-        }
-
-        detach();
-
-#ifdef __cpp_lib_node_extract
-        map.d->m.merge(std::move(d->m));
-#else
-        map.d->m.insert(std::make_move_iterator(d->m.begin()),
-                        std::make_move_iterator(d->m.end()));
-#endif
-        *this = std::move(map);
+        unite(std::move(map));
     }
+#endif
 
     iterator replace(const Key &key, const T &value)
     {
@@ -1408,6 +1392,29 @@ public:
         d->m = std::move(copy);
         return *this;
     }
+
+    QMultiMap &unite(QMultiMap<Key, T> &&other)
+    {
+        if (!other.d || other.d->m.empty())
+            return *this;
+
+        if (other.d.isShared()) {
+            // fall back to a regular copy
+            unite(other);
+            return *this;
+        }
+
+        detach();
+
+#ifdef __cpp_lib_node_extract
+        other.d->m.merge(std::move(d->m));
+#else
+        other.d->m.insert(std::make_move_iterator(d->m.begin()),
+                          std::make_move_iterator(d->m.end()));
+#endif
+        *this = std::move(other);
+        return *this;
+    }
 };
 
 Q_DECLARE_ASSOCIATIVE_ITERATOR(MultiMap)

src/corelib/tools/qmultimap.qdoc

@@ -865,15 +865,17 @@
 
     Inserts all the items in \a map into this map.
 */
-#endif
 
 /*! \fn template <class Key, class T> void QMultiMap<Key, T>::insert(QMultiMap<Key, T> &&map)
     \since 5.15
+    \obsolete Use unite() instead.
+    \overload
 
     Moves all the items from \a map into this map.
 
     If \a map is shared, then the items will be copied instead.
 */
+#endif
 
 /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::replace(const Key &key, const T &value)
 
@@ -947,6 +949,16 @@
     key multiple times.
 */
 
+/*!
+    \fn template <class Key, class T> QMultiMap<Key, T> &QMultiMap<Key, T>::unite(QMultiMap<Key, T> &&other)
+
+    Moves all the items from the \a other map into this map. If a
+    key is common to both maps, the resulting map will contain the
+    key multiple times.
+
+    If \a other is shared, then the items will be copied instead.
+*/
+
 /*! \fn template <class Key, class T> QMultiMap<Key, T> operator+=(QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
 
     Inserts all the items in the \a rhs map into the \a lhs map and