Qt 6: Deprecate QHash::insertMulti

[ChangeLog][QtCore][QHash] insertMulti(), unite() and
values(const Key &key) are now deprecated. Please use
QMultiHash instead.

Change-Id: Ic14907fd5fd38d585708e2dcf2c0200d221ebb25
Reviewed-by: Timur Pocheptsov <timur.pocheptsov@qt.io>

src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp

@@ -119,22 +119,6 @@ hash.insert("plenty", 2000);
 //! [9]
 
 
-//! [10]
-QList<int> values = hash.values("plenty");
-for (int i = 0; i < values.size(); ++i)
-    cout << values.at(i) << Qt::endl;
-//! [10]
-
-
-//! [11]
-QHash<QString, int>::iterator i = hash.find("plenty");
-while (i != hash.end() && i.key() == "plenty") {
-    cout << i.value() << Qt::endl;
-    ++i;
-}
-//! [11]
-
-
 //! [12]
 QHash<QString, int> hash;
 ...

src/corelib/kernel/qvariant.cpp

@@ -972,7 +972,7 @@ static bool convert(const QVariant::Private *d, int t, void *result, bool *ok)
             const QVariantMap *map = v_cast<QVariantMap>(d);
             const auto end = map->end();
             for (auto it = map->begin(); it != end; ++it)
-                hash->insertMulti(it.key(), it.value());
+                static_cast<QMultiHash<QString, QVariant> *>(hash)->insert(it.key(), it.value());
 #ifndef QT_BOOTSTRAPPED
         } else if (d->type == QMetaType::QCborValue) {
             if (!v_cast<QCborValue>(d)->isMap())

src/corelib/kernel/qvariant.h

@@ -825,7 +825,7 @@ namespace QtPrivate {
                 QVariantHash l;
                 l.reserve(iter.size());
                 for (QAssociativeIterable::const_iterator it = iter.begin(), end = iter.end(); it != end; ++it)
-                    l.insertMulti(it.key().toString(), it.value());
+                    static_cast<QMultiHash<QString, QVariant> &>(l).insert(it.key().toString(), it.value());
                 return l;
             }
             return QVariantValueHelper<QVariantHash>::invoke(v);

src/corelib/serialization/qdatastream.h

@@ -301,7 +301,10 @@ QDataStream &readAssociativeContainer(QDataStream &s, Container &c)
             c.clear();
             break;
         }
+QT_WARNING_PUSH
+QT_WARNING_DISABLE_DEPRECATED
         c.insertMulti(k, t);
+QT_WARNING_POP
     }
 
     return s;

src/corelib/tools/qhash.cpp

@@ -1120,21 +1120,6 @@ uint qHash(long double key, uint seed) noexcept
 
     \snippet code/src_corelib_tools_qhash.cpp 9
 
-    However, you can store multiple values per key by using
-    insertMulti() instead of insert() (or using the convenience
-    subclass QMultiHash). If you want to retrieve all
-    the values for a single key, you can use values(const Key &key),
-    which returns a QList<T>:
-
-    \snippet code/src_corelib_tools_qhash.cpp 10
-
-    The items that share the same key are available from most
-    recently to least recently inserted. A more efficient approach is
-    to call find() to get the iterator for the first item with a key
-    and iterate from there:
-
-    \snippet code/src_corelib_tools_qhash.cpp 11
-
     If you only need to extract the values from a hash (not the keys),
     you can also use \l{foreach}:
 
@@ -1435,9 +1420,8 @@ uint qHash(long double key, uint seed) noexcept
 /*! \fn template <class Key, class T> int QHash<Key, T>::remove(const Key &key)
 
     Removes all the items that have the \a key from the hash.
-    Returns the number of items removed which is usually 1 but will
+    Returns the number of items removed which is 1 if the key exists in the hash,
-    be 0 if the key isn't in the hash, or greater than 1 if
+    and 0 otherwise.
-    insertMulti() has been used with the \a key.
 
     \sa clear(), take(), QMultiHash::remove()
 */
@@ -1507,27 +1491,25 @@ uint qHash(long double key, uint seed) noexcept
 
 /*! \fn template <class Key, class T> QList<Key> QHash<Key, T>::uniqueKeys() const
     \since 4.2
+    \obsolete
 
     Returns a list containing all the keys in the map. Keys that occur multiple
     times in the map (because items were inserted with insertMulti(), or
     unite() was used) occur only once in the returned list.
 
-    \sa keys(), values()
+    \sa QMultiHash::uniqueKeys()
 */
 
 /*! \fn template <class Key, class T> QList<Key> QHash<Key, T>::keys() const
 
     Returns a list containing all the keys in the hash, in an
     arbitrary order. Keys that occur multiple times in the hash
-    (because items were inserted with insertMulti(), or unite() was
+    (because the method is operating on a QMultiHash) also occur
-    used) also occur multiple times in the list.
+    multiple times in the list.
-
-    To obtain a list of unique keys, where each key from the map only
-    occurs once, use uniqueKeys().
 
     The order is guaranteed to be the same as that used by values().
 
-    \sa uniqueKeys(), values(), key()
+    \sa QMultiMap::uniqueKeys(), values(), key()
 */
 
 /*! \fn template <class Key, class T> QList<Key> QHash<Key, T>::keys(const T &value) const
@@ -1555,7 +1537,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QList<T> QHash<Key, T>::values(const Key &key) const
-
+    \obsolete
     \overload
 
     Returns a list of all the values associated with the \a key,
@@ -1592,6 +1574,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> int QHash<Key, T>::count(const Key &key) const
+    \obsolete
 
     Returns the number of items associated with the \a key.
 
@@ -1803,8 +1786,6 @@ uint qHash(long double key, uint seed) noexcept
 
     If there are multiple items with the \a key, the most
     recently inserted item's value is replaced with \a value.
-
-    \sa insertMulti()
 */
 
 /*! \fn template <class Key, class T> void QHash<Key, T>::insert(const QHash &other)
@@ -1820,6 +1801,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::iterator QHash<Key, T>::insertMulti(const Key &key, const T &value)
+    \obsolete
 
     Inserts a new item with the \a key and a value of \a value.
 
@@ -1828,16 +1810,17 @@ uint qHash(long double key, uint seed) noexcept
     different from insert(), which overwrites the value of an
     existing item.)
 
+    This function is obsolete. Use QMultiHash or QMultiMap instead.
+
     \sa insert(), values()
 */
 
 /*! \fn template <class Key, class T> QHash &QHash<Key, T>::unite(const QHash &other)
+    \obsolete
 
     Inserts all the items in the \a other hash into this hash. If a
     key is common to both hashes, the resulting hash will contain the
     key multiple times.
-
-    \sa insertMulti()
 */
 
 /*! \fn template <class Key, class T> bool QHash<Key, T>::empty() const
@@ -1978,10 +1961,7 @@ uint qHash(long double key, uint seed) noexcept
     \snippet code/src_corelib_tools_qhash.cpp 17
 
     Unlike QMap, which orders its items by key, QHash stores its
-    items in an arbitrary order. The only guarantee is that items that
+    items in an arbitrary order.
-    share the same key (because they were inserted using
-    QHash::insertMulti()) will appear consecutively, from the most
-    recently to the least recently inserted value.
 
     Let's see a few examples of things we can do with a
     QHash::iterator that we cannot do with a QHash::const_iterator.
@@ -2048,7 +2028,7 @@ uint qHash(long double key, uint seed) noexcept
 
     There is no direct way of changing an item's key through an
     iterator, although it can be done by calling QHash::erase()
-    followed by QHash::insert() or QHash::insertMulti().
+    followed by QHash::insert().
 
     \sa value()
 */
@@ -2210,7 +2190,7 @@ uint qHash(long double key, uint seed) noexcept
     Unlike QMap, which orders its items by key, QHash stores its
     items in an arbitrary order. The only guarantee is that items that
     share the same key (because they were inserted using
-    QHash::insertMulti()) will appear consecutively, from the most
+    a QMultiHash) will appear consecutively, from the most
     recently to the least recently inserted value.
 
     Multiple iterators can be used on the same hash. However, be aware
@@ -2543,18 +2523,22 @@ uint qHash(long double key, uint seed) noexcept
     It inherits QHash and extends it with a few convenience functions
     that make it more suitable than QHash for storing multi-valued
     hashes. A multi-valued hash is a hash that allows multiple values
-    with the same key; QHash normally doesn't allow that, unless you
+    with the same key.
-    call QHash::insertMulti().
 
     Because QMultiHash inherits QHash, all of QHash's functionality also
     applies to QMultiHash. For example, you can use isEmpty() to test
     whether the hash is empty, and you can traverse a QMultiHash using
-    QHash's iterator classes (for example, QHashIterator). But in
+    QHash's iterator classes (for example, QHashIterator). But opposed to
-    addition, it provides an insert() function that corresponds to
+    QHash, it provides an insert() function will allow the insertion of
-    QHash::insertMulti(), and a replace() function that corresponds to
+    multiple items with the same key. The replace() function corresponds to
     QHash::insert(). It also provides convenient operator+() and
     operator+=().
 
+    Unlike QMultiMap, QMultiHash does not provide and ordering of the
+    inserted items. The only guarantee is that items that
+    share the same key will appear consecutively, from the most
+    recently to the least recently inserted value.
+
     Example:
     \snippet code/src_corelib_tools_qhash.cpp 24
 
@@ -2645,7 +2629,8 @@ uint qHash(long double key, uint seed) noexcept
     \sa replace()
 */
 
-/*! \fn template <class Key, class T> QMultiHash &QMultiHash<Key, T>::operator+=(const QMultiHash &other)
+/*! \fn template <class Key, class T> QMultiHash &QMultiHash<Key, T>::unite(const QMultiHash &other)
+    \since 5.13
 
     Inserts all the items in the \a other hash into this hash
     and returns a reference to this hash.
@@ -2653,6 +2638,32 @@ uint qHash(long double key, uint seed) noexcept
     \sa insert()
 */
 
+/*! \fn template <class Key, class T> QList<Key> QHash<Key, T>::uniqueKeys() const
+    \since 5.13
+
+    Returns a list containing all the keys in the map. Keys that occur multiple
+    times in the map occur only once in the returned list.
+
+    \sa keys(), values()
+*/
+
+/*! \fn template <class Key, class T> QList<T> QMultiHash<Key, T>::values(const Key &key) const
+    \overload
+
+    Returns a list of all the values associated with the \a key,
+    from the most recently inserted to the least recently inserted.
+
+    \sa count(), insert()
+*/
+
+/*! \fn template <class Key, class T> QMultiHash &QMultiHash<Key, T>::operator+=(const QMultiHash &other)
+
+    Inserts all the items in the \a other hash into this hash
+    and returns a reference to this hash.
+
+    \sa unit(), insert()
+*/
+
 /*! \fn template <class Key, class T> QMultiHash QMultiHash<Key, T>::operator+(const QMultiHash &other) const
 
     Returns a hash that contains all the items in this hash in
@@ -2682,6 +2693,13 @@ uint qHash(long double key, uint seed) noexcept
     \sa QHash::remove()
 */
 
+/*! \fn template <class Key, class T> int QMultiHash<Key, T>::count(const Key &key) const
+
+    Returns the number of items associated with the \a key.
+
+    \sa contains(), insert()
+*/
+
 /*!
     \fn template <class Key, class T> int QMultiHash<Key, T>::count(const Key &key, const T &value) const
     \since 4.3

src/corelib/tools/qhash.h

@@ -308,12 +308,14 @@ public:
     T &operator[](const Key &key);
     const T operator[](const Key &key) const;
 
-    QList<Key> uniqueKeys() const;
     QList<Key> keys() const;
     QList<Key> keys(const T &value) const;
     QList<T> values() const;
-    QList<T> values(const Key &key) const;
+#if QT_DEPRECATED_SINCE(5, 15)
-    int count(const Key &key) const;
+    QT_DEPRECATED_X("Use QMultiHash for hashes storing multiple values with the same key.") QList<Key> uniqueKeys() const;
+    QT_DEPRECATED_X("Use QMultiHash for hashes storing multiple values with the same key.") QList<T> values(const Key &key) const;
+    QT_DEPRECATED_X("Use QMultiHash for hashes storing multiple values with the same key.") int count(const Key &key) const;
+#endif
 
     class const_iterator;
 
@@ -388,6 +390,7 @@ public:
     {
         friend class iterator;
         friend class QHash<Key, T>;
+        friend class QMultiHash<Key, T>;
         friend class QSet<Key>;
         QHashData::Node *i;
 
@@ -527,8 +530,10 @@ public:
     const_iterator constFind(const Key &key) const;
     iterator insert(const Key &key, const T &value);
     void insert(const QHash &hash);
-    iterator insertMulti(const Key &key, const T &value);
+#if QT_DEPRECATED_SINCE(5, 15)
-    QHash &unite(const QHash &other);
+    QT_DEPRECATED_X("Use QMultiHash for hashes storing multiple values with the same key.") iterator insertMulti(const Key &key, const T &value);
+    QT_DEPRECATED_X("Use QMultiHash for hashes storing multiple values with the same key.") QHash &unite(const QHash &other);
+#endif
 
     // STL compatibility
     typedef T mapped_type;
@@ -570,6 +575,7 @@ private:
 #endif
     }
     friend class QSet<Key>;
+    friend class QMultiHash<Key, T>;
 };
 
 
@@ -607,38 +613,6 @@ QHash<Key, T>::createNode(uint ah, const Key &akey, const T &avalue, Node **anex
     return node;
 }
 
-template <class Key, class T>
-Q_INLINE_TEMPLATE QHash<Key, T> &QHash<Key, T>::unite(const QHash &other)
-{
-    if (d == &QHashData::shared_null) {
-        *this = other;
-    } else {
-#if QT_DEPRECATED_SINCE(5, 15)
-        QHash copy(other);
-        const_iterator it = copy.constEnd();
-        while (it != copy.constBegin()) {
-            it.i = QHashData::previousNode(it.i);
-            insertMulti(it.key(), it.value());
-        }
-#else
-        QHash copy(other);
-        const_iterator it = copy.cbegin();
-        const const_iterator end = copy.cend();
-        while (it != end) {
-            const auto rangeStart = it++;
-            while (it != end && rangeStart.key() == it.key())
-                ++it;
-            const qint64 last = std::distance(rangeStart, it) - 1;
-            for (qint64 i = last; i >= 0; --i) {
-                auto next = std::next(rangeStart, i);
-                insertMulti(next.key(), next.value());
-            }
-        }
-#endif
-    }
-    return *this;
-}
-
 template <class Key, class T>
 Q_OUTOFLINE_TEMPLATE void QHash<Key, T>::freeData(QHashData *x)
 {
@@ -697,26 +671,6 @@ Q_INLINE_TEMPLATE const T QHash<Key, T>::value(const Key &akey, const T &adefaul
     }
 }
 
-template <class Key, class T>
-Q_OUTOFLINE_TEMPLATE QList<Key> QHash<Key, T>::uniqueKeys() const
-{
-    QList<Key> res;
-    res.reserve(size()); // May be too much, but assume short lifetime
-    const_iterator i = begin();
-    if (i != end()) {
-        for (;;) {
-            const Key &aKey = i.key();
-            res.append(aKey);
-            do {
-                if (++i == end())
-                    goto break_out_of_outer_loop;
-            } while (aKey == i.key());
-        }
-    }
-break_out_of_outer_loop:
-    return res;
-}
-
 template <class Key, class T>
 Q_OUTOFLINE_TEMPLATE QList<Key> QHash<Key, T>::keys() const
 {
@@ -775,32 +729,6 @@ Q_OUTOFLINE_TEMPLATE QList<T> QHash<Key, T>::values() const
     return res;
 }
 
-template <class Key, class T>
-Q_OUTOFLINE_TEMPLATE QList<T> QHash<Key, T>::values(const Key &akey) const
-{
-    QList<T> res;
-    Node *node = *findNode(akey);
-    if (node != e) {
-        do {
-            res.append(node->value);
-        } while ((node = node->next) != e && node->key == akey);
-    }
-    return res;
-}
-
-template <class Key, class T>
-Q_OUTOFLINE_TEMPLATE int QHash<Key, T>::count(const Key &akey) const
-{
-    int cnt = 0;
-    Node *node = *findNode(akey);
-    if (node != e) {
-        do {
-            ++cnt;
-        } while ((node = node->next) != e && node->key == akey);
-    }
-    return cnt;
-}
-
 template <class Key, class T>
 Q_INLINE_TEMPLATE const T QHash<Key, T>::operator[](const Key &akey) const
 {
@@ -866,18 +794,6 @@ Q_INLINE_TEMPLATE void QHash<Key, T>::insert(const QHash &hash)
     }
 }
 
-template <class Key, class T>
-Q_INLINE_TEMPLATE typename QHash<Key, T>::iterator QHash<Key, T>::insertMulti(const Key &akey,
-                                                                              const T &avalue)
-{
-    detach();
-    d->willGrow();
-
-    uint h;
-    Node **nextNode = findNode(akey, &h);
-    return iterator(createNode(h, akey, avalue, nextNode));
-}
-
 template <class Key, class T>
 Q_OUTOFLINE_TEMPLATE int QHash<Key, T>::remove(const Key &akey)
 {
@@ -1128,11 +1044,12 @@ public:
     inline typename QHash<Key, T>::iterator replace(const Key &key, const T &value)
     { return QHash<Key, T>::insert(key, value); }
 
-    inline typename QHash<Key, T>::iterator insert(const Key &key, const T &value)
+    typename QHash<Key, T>::iterator insert(const Key &key, const T &value);
-    { return QHash<Key, T>::insertMulti(key, value); }
+
+    inline QMultiHash &unite(const QMultiHash &other);
 
     inline QMultiHash &operator+=(const QMultiHash &other)
-    { this->unite(other); return *this; }
+    { return unite(other); }
     inline QMultiHash operator+(const QMultiHash &other) const
     { QMultiHash result = *this; result += other; return result; }
 
@@ -1141,13 +1058,27 @@ public:
     using QHash<Key, T>::count;
     using QHash<Key, T>::find;
     using QHash<Key, T>::constFind;
+    using QHash<Key, T>::values;
+    using QHash<Key, T>::findNode;
+    using QHash<Key, T>::createNode;
+    using QHash<Key, T>::concrete;
+    using QHash<Key, T>::detach;
+
+    using typename QHash<Key, T>::Node;
+    using typename QHash<Key, T>::iterator;
+    using typename QHash<Key, T>::const_iterator;
 
     bool contains(const Key &key, const T &value) const;
 
     int remove(const Key &key, const T &value);
 
+    int count(const Key &key) const;
     int count(const Key &key, const T &value) const;
 
+    QList<Key> uniqueKeys() const;
+
+    QList<T> values(const Key &akey) const;
+
     typename QHash<Key, T>::iterator find(const Key &key, const T &value) {
         typename QHash<Key, T>::iterator i(find(key));
         typename QHash<Key, T>::iterator end(this->end());
@@ -1175,6 +1106,50 @@ private:
     const T operator[](const Key &key) const;
 };
 
+template <class Key, class T>
+Q_INLINE_TEMPLATE typename QHash<Key, T>::iterator QMultiHash<Key, T>::insert(const Key &akey, const T &avalue)
+{
+    detach();
+    this->d->willGrow();
+
+    uint h;
+    Node **nextNode = findNode(akey, &h);
+    return iterator(createNode(h, akey, avalue, nextNode));
+}
+
+template <class Key, class T>
+Q_INLINE_TEMPLATE QMultiHash<Key, T> &QMultiHash<Key, T>::unite(const QMultiHash &other)
+{
+    if (this->d == &QHashData::shared_null) {
+        *this = other;
+    } else {
+#if QT_DEPRECATED_SINCE(5, 15)
+        QMultiHash copy(other);
+        const_iterator it = copy.constEnd();
+        while (it != copy.constBegin()) {
+            it.i = QHashData::previousNode(it.i);
+            insert(it.key(), it.value());
+        }
+#else
+        const QMultiHash copy(other);
+        const_iterator it = copy.cbegin();
+        const const_iterator end = copy.cend();
+        while (it != end) {
+            const auto rangeStart = it++;
+            while (it != end && rangeStart.key() == it.key())
+                ++it;
+            const qint64 last = std::distance(rangeStart, it) - 1;
+            for (qint64 i = last; i >= 0; --i) {
+                auto next = std::next(rangeStart, i);
+                insert(next.key(), next.value());
+            }
+        }
+#endif
+    }
+    return *this;
+}
+
+
 template <class Key, class T>
 Q_INLINE_TEMPLATE bool QMultiHash<Key, T>::contains(const Key &key, const T &value) const
 {
@@ -1212,7 +1187,84 @@ Q_INLINE_TEMPLATE int QMultiHash<Key, T>::count(const Key &key, const T &value)
     return n;
 }
 
-template<class Key, class T>
+template <class Key, class T>
+Q_OUTOFLINE_TEMPLATE QList<Key> QMultiHash<Key, T>::uniqueKeys() const
+{
+    QList<Key> res;
+    res.reserve(QHash<Key, T>::size()); // May be too much, but assume short lifetime
+    typename QHash<Key, T>::const_iterator i = QHash<Key, T>::begin();
+    if (i != QHash<Key, T>::end()) {
+        for (;;) {
+            const Key &aKey = i.key();
+            res.append(aKey);
+            do {
+                if (++i == QHash<Key, T>::end())
+                    goto break_out_of_outer_loop;
+            } while (aKey == i.key());
+        }
+    }
+break_out_of_outer_loop:
+    return res;
+}
+
+#if QT_DEPRECATED_SINCE(5, 15)
+
+template <class Key, class T>
+Q_OUTOFLINE_TEMPLATE typename QHash<Key, T>::iterator QHash<Key, T>::insertMulti(const Key &key, const T &value) {
+    return static_cast<QMultiHash<Key, T> *>(this)->insert(key, value);
+}
+
+template <class Key, class T>
+Q_OUTOFLINE_TEMPLATE QHash<Key, T> &QHash<Key, T>::unite(const QHash &other) {
+    return static_cast<QMultiHash<Key, T> *>(this)->unite(other);
+}
+
+template <class Key, class T>
+Q_OUTOFLINE_TEMPLATE QList<T> QHash<Key, T>::values(const Key &akey) const
+{
+    return static_cast<const QMultiHash<Key, T> *>(this)->values(akey);
+}
+
+template <class Key, class T>
+Q_OUTOFLINE_TEMPLATE int QHash<Key, T>::count(const Key &akey) const
+{
+    return static_cast<const QMultiHash<Key, T> *>(this)->count(akey);
+}
+
+template <class Key, class T>
+Q_OUTOFLINE_TEMPLATE QList<Key> QHash<Key, T>::uniqueKeys() const
+{
+    return static_cast<const QMultiHash<Key, T> *>(this)->uniqueKeys();
+}
+#endif
+
+template <class Key, class T>
+Q_OUTOFLINE_TEMPLATE QList<T> QMultiHash<Key, T>::values(const Key &akey) const
+{
+    QList<T> res;
+    Node *node = *findNode(akey);
+    if (node != this->e) {
+        do {
+            res.append(node->value);
+        } while ((node = node->next) != this->e && node->key == akey);
+    }
+    return res;
+}
+
+template <class Key, class T>
+Q_OUTOFLINE_TEMPLATE int QMultiHash<Key, T>::count(const Key &akey) const
+{
+    int cnt = 0;
+    Node *node = *findNode(akey);
+    if (node != this->e) {
+        do {
+            ++cnt;
+        } while ((node = node->next) != this->e && node->key == akey);
+    }
+    return cnt;
+}
+
+template <class Key, class T>
 class QHashIterator
 {
     typedef typename QHash<Key, T>::const_iterator const_iterator;

src/dbus/qdbusargument.h

@@ -370,7 +370,7 @@ inline const QDBusArgument &operator>>(const QDBusArgument &arg, QHash<Key, T> &
         T value;
         arg.beginMapEntry();
         arg >> key >> value;
-        map.insertMulti(key, value);
+        static_cast<QMultiHash<Key, T> &>(map).insert(key, value);
         arg.endMapEntry();
     }
     arg.endMap();