QRegion: deprecate rects()

It was superseded by begin()/end() in Qt 5.8.

The eventual removal of rects() will allow greater flexibility
in the implementation's choice of data structure (std::vector,
e.g., or QVarLengthArray).

Remove all traces of rects() from the documentation. This means
we need to copy information previously contained in the rects()
docs to functions which previously just referred to rects(), in
particular the begin()/end() familiy of functions.

Change-Id: I90809809783252f7c552f24b4841f1e965580284
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
Reviewed-by: Lars Knoll <lars.knoll@qt.io>

src/gui/painting/qregion.cpp

@@ -81,8 +81,9 @@ QT_BEGIN_NAMESPACE
     contains() a QPoint or QRect. The bounding rectangle can be found
     with boundingRect().
 
-    Iteration over the region (with begin(), end()) gives a decomposition of
-    the region into rectangles. The same sequence of rectangles is returned by rects().
+    Iteration over the region (with begin(), end(), or C++11
+    ranged-for loops) gives a decomposition of the region into
+    rectangles.
 
     Example of using complex regions:
     \snippet code/src_gui_painting_qregion.cpp 0
@@ -755,7 +756,8 @@ QRegion QRegion::intersect(const QRect &r) const
     \fn int QRegion::rectCount() const
     \since 4.6
 
-    Returns the number of rectangles that will be returned in rects().
+    Returns the number of rectangles that this region is composed of.
+    Same as \c{end() - begin()}.
 */
 
 /*!
@@ -917,20 +919,28 @@ QRegion QRegion::intersect(const QRect &r) const
     gives a rectangle that is QRect::isNull().
 */
 
+#if QT_DEPRECATED_SINCE(5, 11)
 /*!
     \fn QVector<QRect> QRegion::rects() const
+    \obsolete
+
+    Use begin() and end() instead.
 
     Returns an array of non-overlapping rectangles that make up the
     region.
 
     The union of all the rectangles is equal to the original region.
 */
+#endif
 
 /*!
     \typedef QRegion::const_iterator
     \since 5.8
 
-    An iterator over the QRects that make up the region.
+    An iterator over the non-overlapping rectangles that make up the
+    region.
+
+    The union of all the rectangles is equal to the original region.
 
     QRegion does not offer mutable iterators.
 
@@ -941,7 +951,10 @@ QRegion QRegion::intersect(const QRect &r) const
     \typedef QRegion::const_reverse_iterator
     \since 5.8
 
-    A reverse iterator over the QRects that make up the region.
+    A reverse iterator over the non-overlapping rectangles that make up the
+    region.
+
+    The union of all the rectangles is equal to the original region.
 
     QRegion does not offer mutable iterators.
 
@@ -953,8 +966,9 @@ QRegion QRegion::intersect(const QRect &r) const
     \since 5.8
 
     Returns a const_iterator pointing to the beginning of the range of
-    rectangles that make up this range, in the order in which rects()
-    returns them.
+    non-overlapping rectangles that make up the region.
+
+    The union of all the rectangles is equal to the original region.
 
     \sa rbegin(), cbegin(), end()
 */
@@ -970,9 +984,10 @@ QRegion QRegion::intersect(const QRect &r) const
     \fn QRegion::end() const
     \since 5.8
 
-    Returns a const_iterator pointing to one past the end of the range of
-    rectangles that make up this range, in the order in which rects()
-    returns them.
+    Returns a const_iterator pointing to one past the end of
+    non-overlapping rectangles that make up the region.
+
+    The union of all the rectangles is equal to the original region.
 
     \sa rend(), cend(), begin()
 */
@@ -988,9 +1003,10 @@ QRegion QRegion::intersect(const QRect &r) const
     \fn QRegion::rbegin() const
     \since 5.8
 
-    Returns a const_reverse_iterator pointing to the beginning of the range of
-    rectangles that make up this range, in the reverse order in which rects()
-    returns them.
+    Returns a const_reverse_iterator pointing to the beginning of the
+    range of non-overlapping rectangles that make up the region.
+
+    The union of all the rectangles is equal to the original region.
 
     \sa begin(), crbegin(), rend()
 */
@@ -1006,9 +1022,10 @@ QRegion QRegion::intersect(const QRect &r) const
     \fn QRegion::rend() const
     \since 5.8
 
-    Returns a const_reverse_iterator pointing to one past the end of the range of
-    rectangles that make up this range, in the reverse order in which rects()
-    returns them.
+    Returns a const_reverse_iterator pointing to one past the end of
+    the range of non-overlapping rectangles that make up the region.
+
+    The union of all the rectangles is equal to the original region.
 
     \sa end(), crend(), rbegin()
 */
@@ -4348,6 +4365,7 @@ bool qt_region_strictContains(const QRegion &region, const QRect &rect)
             && rect.top() >= r1.top() && rect.bottom() <= r1.bottom());
 }
 
+#if QT_DEPRECATED_SINCE(5, 11)
 QVector<QRect> QRegion::rects() const
 {
     if (d->qt_rgn) {
@@ -4359,6 +4377,7 @@ QVector<QRect> QRegion::rects() const
         return QVector<QRect>();
     }
 }
+#endif
 
 QRegion::const_iterator QRegion::begin() const Q_DECL_NOTHROW
 {

src/gui/painting/qregion.h

@@ -122,7 +122,10 @@ public:
     bool intersects(const QRect &r) const;
 
     QRect boundingRect() const Q_DECL_NOTHROW;
+#if QT_DEPRECATED_SINCE(5, 11)
+    QT_DEPRECATED_X("Use begin()/end() instead")
     QVector<QRect> rects() const;
+#endif
     void setRects(const QRect *rect, int num);
     int rectCount() const Q_DECL_NOTHROW;
 #ifdef Q_COMPILER_MANGLES_RETURN_TYPE