Deprecate reverse iteration on QSet

std::unordered_set only supports forward iteration for good
reasons. Align our API with this by deprecating reverse
iteration and the operator+/-() for iterators.

[ChangeLog][QtCore][QSet] Reverse iteration over QSet is now
deprecated.

Change-Id: Ia6e3346a6474c454c63010d855850ae4ff12e1a4
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
Reviewed-by: Frederik Gladhorn <frederik.gladhorn@qt.io>

2 files changed, 49 insertions, 29 deletions

diff --git a/src/corelib/tools/qset.h b/src/corelib/tools/qset.h
index 2e72832185..879e2176f2 100644
--- a/src/corelib/tools/qset.h
+++ b/src/corelib/tools/qset.h
@@ -108,7 +108,11 @@ public:
         friend class QSet<T>;
 
     public:
+#if QT_DEPRECATED_SINCE(5, 15)
         typedef std::bidirectional_iterator_tag iterator_category;
+#else
+        typedef std::forward_iterator_tag iterator_category;
+#endif
         typedef qptrdiff difference_type;
         typedef T value_type;
         typedef const T *pointer;
@@ -128,13 +132,15 @@ public:
             { return i != o.i; }
         inline iterator &operator++() { ++i; return *this; }
         inline iterator operator++(int) { iterator r = *this; ++i; return r; }
-        inline iterator &operator--() { --i; return *this; }
-        inline iterator operator--(int) { iterator r = *this; --i; return r; }
-        inline iterator operator+(int j) const { return i + j; }
-        inline iterator operator-(int j) const { return i - j; }
-        friend inline iterator operator+(int j, iterator k) { return k + j; }
-        inline iterator &operator+=(int j) { i += j; return *this; }
-        inline iterator &operator-=(int j) { i -= j; return *this; }
+#if QT_DEPRECATED_SINCE(5, 15)
+        inline QT_DEPRECATED iterator &operator--() { --i; return *this; }
+        inline QT_DEPRECATED iterator operator--(int) { iterator r = *this; --i; return r; }
+        inline QT_DEPRECATED iterator operator+(int j) const { return i + j; }
+        inline QT_DEPRECATED iterator operator-(int j) const { return i - j; }
+        friend inline QT_DEPRECATED iterator operator+(int j, iterator k) { return k + j; }
+        inline QT_DEPRECATED iterator &operator+=(int j) { i += j; return *this; }
+        inline QT_DEPRECATED iterator &operator-=(int j) { i -= j; return *this; }
+#endif
     };
 
     class const_iterator
@@ -145,7 +151,11 @@ public:
         friend class QSet<T>;
 
     public:
+#if QT_DEPRECATED_SINCE(5, 15)
         typedef std::bidirectional_iterator_tag iterator_category;
+#else
+        typedef std::forward_iterator_tag iterator_category;
+#endif
         typedef qptrdiff difference_type;
         typedef T value_type;
         typedef const T *pointer;
@@ -163,19 +173,18 @@ public:
         inline bool operator!=(const const_iterator &o) const { return i != o.i; }
         inline const_iterator &operator++() { ++i; return *this; }
         inline const_iterator operator++(int) { const_iterator r = *this; ++i; return r; }
-        inline const_iterator &operator--() { --i; return *this; }
-        inline const_iterator operator--(int) { const_iterator r = *this; --i; return r; }
-        inline const_iterator operator+(int j) const { return i + j; }
-        inline const_iterator operator-(int j) const { return i - j; }
-        friend inline const_iterator operator+(int j, const_iterator k) { return k + j; }
-        inline const_iterator &operator+=(int j) { i += j; return *this; }
-        inline const_iterator &operator-=(int j) { i -= j; return *this; }
+#if QT_DEPRECATED_SINCE(5, 15)
+        inline QT_DEPRECATED const_iterator &operator--() { --i; return *this; }
+        inline QT_DEPRECATED const_iterator operator--(int) { const_iterator r = *this; --i; return r; }
+        inline QT_DEPRECATED const_iterator operator+(int j) const { return i + j; }
+        inline QT_DEPRECATED const_iterator operator-(int j) const { return i - j; }
+        friend inline QT_DEPRECATED const_iterator operator+(int j, const_iterator k) { return k + j; }
+        inline QT_DEPRECATED const_iterator &operator+=(int j) { i += j; return *this; }
+        inline QT_DEPRECATED const_iterator &operator-=(int j) { i -= j; return *this; }
+#endif
     };
 
     // STL style
-    typedef std::reverse_iterator<iterator> reverse_iterator;
-    typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
-
     inline iterator begin() { return q_hash.begin(); }
     inline const_iterator begin() const noexcept { return q_hash.begin(); }
     inline const_iterator cbegin() const noexcept { return q_hash.begin(); }
@@ -185,12 +194,17 @@ public:
     inline const_iterator cend() const noexcept { return q_hash.end(); }
     inline const_iterator constEnd() const noexcept { return q_hash.constEnd(); }
 
-    reverse_iterator rbegin() { return reverse_iterator(end()); }
-    reverse_iterator rend() { return reverse_iterator(begin()); }
-    const_reverse_iterator rbegin() const noexcept { return const_reverse_iterator(end()); }
-    const_reverse_iterator rend() const noexcept { return const_reverse_iterator(begin()); }
-    const_reverse_iterator crbegin() const noexcept { return const_reverse_iterator(end()); }
-    const_reverse_iterator crend() const noexcept { return const_reverse_iterator(begin()); }
+#if QT_DEPRECATED_SINCE(5, 15)
+    typedef std::reverse_iterator<iterator> reverse_iterator;
+    typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
+
+    reverse_iterator QT_DEPRECATED rbegin() { return reverse_iterator(end()); }
+    reverse_iterator QT_DEPRECATED rend() { return reverse_iterator(begin()); }
+    const_reverse_iterator QT_DEPRECATED rbegin() const noexcept { return const_reverse_iterator(end()); }
+    const_reverse_iterator QT_DEPRECATED rend() const noexcept { return const_reverse_iterator(begin()); }
+    const_reverse_iterator QT_DEPRECATED crbegin() const noexcept { return const_reverse_iterator(end()); }
+    const_reverse_iterator QT_DEPRECATED crend() const noexcept { return const_reverse_iterator(begin()); }
+#endif
 
     iterator erase(iterator i)
     { return erase(m2c(i)); }
@@ -429,17 +443,19 @@ public:
     inline bool hasNext() const { return c->constEnd() != i; }
     inline const T &next() { n = i++; return *n; }
     inline const T &peekNext() const { return *i; }
-    inline bool hasPrevious() const { return c->constBegin() != i; }
-    inline const T &previous() { n = --i; return *n; }
-    inline const T &peekPrevious() const { iterator p = i; return *--p; }
     inline void remove()
     { if (c->constEnd() != n) { i = c->erase(n); n = c->end(); } }
     inline const T &value() const { Q_ASSERT(item_exists()); return *n; }
     inline bool findNext(const T &t)
     { while (c->constEnd() != (n = i)) if (*i++ == t) return true; return false; }
-    inline bool findPrevious(const T &t)
+#if QT_DEPRECATED_SINCE(5, 15)
+    inline QT_DEPRECATED bool hasPrevious() const { return c->constBegin() != i; }
+    inline QT_DEPRECATED const T &previous() { n = --i; return *n; }
+    inline QT_DEPRECATED const T &peekPrevious() const { iterator p = i; return *--p; }
+    inline QT_DEPRECATED bool findPrevious(const T &t)
     { while (c->constBegin() != i) if (*(n = --i) == t) return true;
       n = c->end(); return false;  }
+#endif
 };
 #endif // QT_NO_JAVA_STYLE_ITERATORS
 
diff --git a/src/corelib/tools/qset.qdoc b/src/corelib/tools/qset.qdoc
index 084523ed4b..7c752d0318 100644
--- a/src/corelib/tools/qset.qdoc
+++ b/src/corelib/tools/qset.qdoc
@@ -906,8 +906,6 @@
 
     Calling this function on QSet<T>::constEnd() leads to
     undefined results.
-
-    \sa operator--()
 */
 
 /*!
@@ -924,6 +922,7 @@
 /*!
     \fn template <class T> QSet<T>::iterator &QSet<T>::iterator::operator--()
     \fn template <class T> QSet<T>::const_iterator &QSet<T>::const_iterator::operator--()
+    \obsolete
 
     The prefix -- operator (\c{--it}) makes the preceding item
     current and returns an iterator to the new current item.
@@ -937,6 +936,7 @@
 /*!
     \fn template <class T> QSet<T>::iterator QSet<T>::iterator::operator--(int)
     \fn template <class T> QSet<T>::const_iterator QSet<T>::const_iterator::operator--(int)
+    \obsolete
 
     \overload
 
@@ -947,6 +947,7 @@
 /*!
     \fn template <class T> QSet<T>::iterator QSet<T>::iterator::operator+(int j) const
     \fn template <class T> QSet<T>::const_iterator QSet<T>::const_iterator::operator+(int j) const
+    \obsolete
 
     Returns an iterator to the item at \a j positions forward from
     this iterator. (If \a j is negative, the iterator goes backward.)
@@ -959,6 +960,7 @@
 /*!
     \fn template <class T> QSet<T>::iterator QSet<T>::iterator::operator-(int j) const
     \fn template <class T> QSet<T>::const_iterator QSet<T>::const_iterator::operator-(int j) const
+    \obsolete
 
     Returns an iterator to the item at \a j positions backward from
     this iterator. (If \a j is negative, the iterator goes forward.)
@@ -971,6 +973,7 @@
 /*!
     \fn template <class T> QSet<T>::iterator &QSet<T>::iterator::operator+=(int j)
     \fn template <class T> QSet<T>::const_iterator &QSet<T>::const_iterator::operator+=(int j)
+    \obsolete
 
     Advances the iterator by \a j items. (If \a j is negative, the
     iterator goes backward.)
@@ -983,6 +986,7 @@
 /*!
     \fn template <class T> QSet<T>::iterator &QSet<T>::iterator::operator-=(int j)
     \fn template <class T> QSet<T>::const_iterator &QSet<T>::const_iterator::operator-=(int j)
+    \obsolete
 
     Makes the iterator go back by \a j items. (If \a j is negative,
     the iterator goes forward.)