QMap: add operator+ and - for iterators

We missed the chance of deprecating them in 5.15, so
they'll just add to the pain of porting to 6.0. We
should not keep them around forever, though; QMap isn't
random access and so its iterators should only have
bidirectional APIs.

Fixes: QTBUG-95334
Change-Id: I3577f7d25e8ab793722d2f220fd27bc85c622b0d
Reviewed-by: Lars Knoll <lars.knoll@qt.io>
(cherry picked from commit cc584c59de644195ae0c4f7f99ad428e189df07d)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

4 files changed, 194 insertions, 0 deletions

diff --git a/src/corelib/tools/qmap.h b/src/corelib/tools/qmap.h
index f71e95dd82..cb3804308c 100644
--- a/src/corelib/tools/qmap.h
+++ b/src/corelib/tools/qmap.h
@@ -496,6 +496,26 @@ public:
             --i;
             return r;
         }
+
+#if QT_DEPRECATED_SINCE(6, 0)
+        QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMap iterators are not random access")
+        friend iterator operator+(iterator it, difference_type j) { return std::next(it, j); }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMap iterators are not random access")
+        friend iterator operator-(iterator it, difference_type j) { return std::prev(it, j); }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::next or std::advance; QMap iterators are not random access")
+        iterator &operator+=(difference_type j) { std::advance(*this, j); return *this; }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::prev or std::advance; QMap iterators are not random access")
+        iterator &operator-=(difference_type j) { std::advance(*this, -j); return *this; }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMap iterators are not random access")
+        friend iterator operator+(difference_type j, iterator it) { return std::next(it, j); }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMap iterators are not random access")
+        friend iterator operator-(difference_type j, iterator it) { return std::prev(it, j); }
+#endif
     };
 
     class const_iterator
@@ -543,6 +563,26 @@ public:
             --i;
             return r;
         }
+
+#if QT_DEPRECATED_SINCE(6, 0)
+        QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMap iterators are not random access")
+        friend const_iterator operator+(const_iterator it, difference_type j) { return std::next(it, j); }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMap iterators are not random access")
+        friend const_iterator operator-(const_iterator it, difference_type j) { return std::prev(it, j); }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::next or std::advance; QMap iterators are not random access")
+        const_iterator &operator+=(difference_type j) { std::advance(*this, j); return *this; }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::prev or std::advance; QMap iterators are not random access")
+        const_iterator &operator-=(difference_type j) { std::advance(*this, -j); return *this; }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMap iterators are not random access")
+        friend const_iterator operator+(difference_type j, const_iterator it) { return std::next(it, j); }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMap iterators are not random access")
+        friend const_iterator operator-(difference_type j, const_iterator it) { return std::prev(it, j); }
+#endif
     };
 
     class key_iterator
@@ -1130,6 +1170,26 @@ public:
             --i;
             return r;
         }
+
+#if QT_DEPRECATED_SINCE(6, 0)
+        QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMultiMap iterators are not random access")
+        friend iterator operator+(iterator it, difference_type j) { return std::next(it, j); }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMultiMap iterators are not random access")
+        friend iterator operator-(iterator it, difference_type j) { return std::prev(it, j); }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::next or std::advance; QMultiMap iterators are not random access")
+        iterator &operator+=(difference_type j) { std::advance(*this, j); return *this; }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::prev or std::advance; QMultiMap iterators are not random access")
+        iterator &operator-=(difference_type j) { std::advance(*this, -j); return *this; }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMultiMap iterators are not random access")
+        friend iterator operator+(difference_type j, iterator it) { return std::next(it, j); }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMultiMap iterators are not random access")
+        friend iterator operator-(difference_type j, iterator it) { return std::prev(it, j); }
+#endif
     };
 
     class const_iterator
@@ -1177,6 +1237,26 @@ public:
             --i;
             return r;
         }
+
+#if QT_DEPRECATED_SINCE(6, 0)
+        QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMultiMap iterators are not random access")
+        friend const_iterator operator+(const_iterator it, difference_type j) { return std::next(it, j); }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMultiMap iterators are not random access")
+        friend const_iterator operator-(const_iterator it, difference_type j) { return std::prev(it, j); }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::next or std::advance; QMultiMap iterators are not random access")
+        const_iterator &operator+=(difference_type j) { std::advance(*this, j); return *this; }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::prev or std::advance; QMultiMap iterators are not random access")
+        const_iterator &operator-=(difference_type j) { std::advance(*this, -j); return *this; }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMultiMap iterators are not random access")
+        friend const_iterator operator+(difference_type j, const_iterator it) { return std::next(it, j); }
+
+        QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMultiMap iterators are not random access")
+        friend const_iterator operator-(difference_type j, const_iterator it) { return std::prev(it, j); }
+#endif
     };
 
     class key_iterator
diff --git a/src/corelib/tools/qmap.qdoc b/src/corelib/tools/qmap.qdoc
index e7b412b0d9..0a9956502f 100644
--- a/src/corelib/tools/qmap.qdoc
+++ b/src/corelib/tools/qmap.qdoc
@@ -1063,6 +1063,24 @@
     current item.
 */
 
+/*! \fn template <class Key, class T> QMap<Key, T>::iterator operator+(QMap<Key, T>::iterator, difference_type n)
+    \fn template <class Key, class T> QMap<Key, T>::iterator operator+(difference_type n, QMap<Key, T>::iterator)
+    \fn template <class Key, class T> QMap<Key, T>::iterator operator-(QMap<Key, T>::iterator, difference_type n)
+    \fn template <class Key, class T> QMap<Key, T>::iterator operator-(difference_type n, QMap<Key, T>::iterator)
+    \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator+=(difference_type n)
+    \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator-=(difference_type n)
+
+    \obsolete
+
+    \since 6.2
+
+    Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
+
+    Moves an iterator by \e{n} positions. These operations can be
+    expensive for large values of \e{n}; QMap iterators are not
+    random access.
+*/
+
 /*! \class QMap::const_iterator
     \inmodule QtCore
     \brief The QMap::const_iterator class provides an STL-style const iterator for QMap.
@@ -1217,6 +1235,24 @@
     current item.
 */
 
+/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator operator+(QMap<Key, T>::const_iterator, difference_type n)
+    \fn template <class Key, class T> QMap<Key, T>::const_iterator operator+(difference_type n, QMap<Key, T>::const_iterator)
+    \fn template <class Key, class T> QMap<Key, T>::const_iterator operator-(QMap<Key, T>::const_iterator, difference_type n)
+    \fn template <class Key, class T> QMap<Key, T>::const_iterator operator-(difference_type n, QMap<Key, T>::const_iterator)
+    \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator+=(difference_type n)
+    \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator-=(difference_type n)
+
+    \obsolete
+
+    \since 6.2
+
+    Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
+
+    Moves an iterator by \e{n} positions. These operations can be
+    expensive for large values of \e{n}. QMap iterators are not
+    random access.
+*/
+
 /*! \class QMap::key_iterator
     \inmodule QtCore
     \since 5.6
diff --git a/src/corelib/tools/qmultimap.qdoc b/src/corelib/tools/qmultimap.qdoc
index 913d4155d7..bd17a03ba2 100644
--- a/src/corelib/tools/qmultimap.qdoc
+++ b/src/corelib/tools/qmultimap.qdoc
@@ -1197,6 +1197,22 @@
     current item.
 */
 
+/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator operator+(QMultiMap<Key, T>::iterator, difference_type n)
+    \fn template <class Key, class T> QMultiMap<Key, T>::iterator operator+(difference_type n, QMultiMap<Key, T>::iterator)
+    \fn template <class Key, class T> QMultiMap<Key, T>::iterator operator-(QMultiMap<Key, T>::iterator, difference_type n)
+    \fn template <class Key, class T> QMultiMap<Key, T>::iterator operator-(difference_type n, QMultiMap<Key, T>::iterator)
+    \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator+=(difference_type n)
+    \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator-=(difference_type n)
+
+    \obsolete
+
+    Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
+
+    Move an iterator by \e{n} positions. These operations can be
+    expensive for large values of \e{n}; QMultiMap iterators are not
+    random access.
+*/
+
 /*! \class QMultiMap::const_iterator
     \inmodule QtCore
     \brief The QMultiMap::const_iterator class provides an STL-style const iterator for QMultiMap.
@@ -1353,6 +1369,22 @@
     current item.
 */
 
+/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator operator+(QMultiMap<Key, T>::const_iterator, difference_type n)
+    \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator operator+(difference_type n, QMultiMap<Key, T>::const_iterator)
+    \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator operator-(QMultiMap<Key, T>::const_iterator, difference_type n)
+    \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator operator-(difference_type n, QMultiMap<Key, T>::const_iterator)
+    \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator+=(difference_type n)
+    \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator-=(difference_type n)
+
+    \obsolete
+
+    Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
+
+    Move an iterator by \e{n} positions. These operations can be
+    expensive for large values of \e{n}. QMultiMap iterators are not
+    random access.
+*/
+
 /*! \class QMultiMap::key_iterator
     \inmodule QtCore
     \since 5.6
diff --git a/tests/auto/corelib/tools/qmap/tst_qmap.cpp b/tests/auto/corelib/tools/qmap/tst_qmap.cpp
index 3e9a51cf2c..e5bddb5d8d 100644
--- a/tests/auto/corelib/tools/qmap/tst_qmap.cpp
+++ b/tests/auto/corelib/tools/qmap/tst_qmap.cpp
@@ -1129,6 +1129,29 @@ void tst_QMap::iterators()
             QVERIFY(stlIt.value() == testString.arg(i));
     QCOMPARE(i, 100);
 
+    // Same but exercising deprecated APIs
+QT_WARNING_PUSH
+QT_WARNING_DISABLE_DEPRECATED
+    stlIt = map.begin();
+    QCOMPARE(stlIt.value(), QLatin1String("Teststring 1"));
+
+    stlIt += 5;
+    QCOMPARE(stlIt.value(), QLatin1String("Teststring 6"));
+
+    stlIt++;
+    QCOMPARE(stlIt.value(), QLatin1String("Teststring 7"));
+
+    stlIt = stlIt - 3;
+    QCOMPARE(stlIt.value(), QLatin1String("Teststring 4"));
+
+    stlIt--;
+    QCOMPARE(stlIt.value(), QLatin1String("Teststring 3"));
+
+    for(stlIt = map.begin(), i = 1; stlIt != map.end(); ++stlIt, ++i)
+            QVERIFY(stlIt.value() == testString.arg(i));
+    QCOMPARE(i, 100);
+QT_WARNING_POP
+
     //STL-Style const-iterators
 
     QMap<int, QString>::const_iterator cstlIt = map.constBegin();
@@ -1150,6 +1173,29 @@ void tst_QMap::iterators()
             QVERIFY(cstlIt.value() == testString.arg(i));
     QCOMPARE(i, 100);
 
+    // Same but exercising deprecated APIs
+QT_WARNING_PUSH
+QT_WARNING_DISABLE_DEPRECATED
+    cstlIt = map.constBegin();
+    QCOMPARE(cstlIt.value(), QLatin1String("Teststring 1"));
+
+    cstlIt += 5;
+    QCOMPARE(cstlIt.value(), QLatin1String("Teststring 6"));
+
+    cstlIt++;
+    QCOMPARE(cstlIt.value(), QLatin1String("Teststring 7"));
+
+    cstlIt = cstlIt - 3;
+    QCOMPARE(cstlIt.value(), QLatin1String("Teststring 4"));
+
+    cstlIt--;
+    QCOMPARE(cstlIt.value(), QLatin1String("Teststring 3"));
+
+    for(cstlIt = map.constBegin(), i = 1; cstlIt != map.constEnd(); ++cstlIt, ++i)
+            QVERIFY(cstlIt.value() == testString.arg(i));
+    QCOMPARE(i, 100);
+QT_WARNING_POP
+
     //Java-Style iterators
 
     QMapIterator<int, QString> javaIt(map);