Documentation: Expand documentation on how to iterate Qt containers

Introduce a section on iteration and add range-based for and index.

Pick-to: 6.4 6.2
Task-number: QTBUG-108687
Change-Id: Icb1ff55049361769f7c0b042d42f70148dd07c2e
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>

2 files changed, 48 insertions, 4 deletions

diff --git a/src/corelib/doc/snippets/code/doc_src_containers.cpp b/src/corelib/doc/snippets/code/doc_src_containers.cpp
index ab7f8c8b7f..29d9b584d0 100644
--- a/src/corelib/doc/snippets/code/doc_src_containers.cpp
+++ b/src/corelib/doc/snippets/code/doc_src_containers.cpp
@@ -16,6 +16,27 @@ private:
 };
 //! [0]
 
+//! [range_for]
+QList<QString> list = {"A", "B", "C", "D"};
+for (const auto &item : list) {
+   ...
+}
+//! [range_for]
+
+//! [range_for_as_const]
+QList<QString> list = {"A", "B", "C", "D"};
+for (const auto &item : std::as_const(list)) {
+    ...
+}
+//! [range_for_as_const]
+
+//! [index]
+QList<QString> list = {"A", "B", "C", "D"};
+for (qsizetype i = 0; i < list.size(); ++i) {
+    const auto &item = list.at(i);
+    ...
+}
+//! [index]
 
 //! [1]
 QList<QString> list = {"A", "B", "C", "D"};
diff --git a/src/corelib/doc/src/containers.qdoc b/src/corelib/doc/src/containers.qdoc
index 65fbd957b0..b5f4029fbe 100644
--- a/src/corelib/doc/src/containers.qdoc
+++ b/src/corelib/doc/src/containers.qdoc
@@ -191,7 +191,30 @@
     the C++ language doesn't specify any initialization; in those
     cases, Qt's containers automatically initialize the value to 0.
 
-    \section1 The Iterator Classes
+    \section1 Iterating over Containers
+
+    \section2 Range-based for
+
+    Range-based \c for should preferably be used for containers:
+
+    \snippet code/doc_src_containers.cpp range_for
+
+    Note that when using a Qt container in a non-const context,
+    \l{implicit sharing} may perform an undesired detach of the container.
+    To prevent this, use \c std::as_const():
+
+    \snippet code/doc_src_containers.cpp range_for_as_const
+
+    For associative containers, this will loop over the values.
+
+    \section2 Index-based
+
+    For sequential containers that store their items contiguously in memory
+    (for example, QList), index-based iteration can be used:
+
+    \snippet code/doc_src_containers.cpp index
+
+    \section2 The Iterator Classes
 
     Iterators provide a uniform means to access items in a container.
     Qt's container classes provide two types of iterators: STL-style
@@ -200,7 +223,7 @@
     from \l{Implicit Sharing}{implicitly shared copies} due to a call
     to a non-const member function.
 
-    \section2 STL-Style Iterators
+    \section3 STL-Style Iterators
 
     STL-style iterators have been available since the release of Qt
     2.0. They are compatible with Qt's and STL's \l{generic
@@ -315,7 +338,7 @@
     This problem doesn't occur with functions that return a const or
     non-const reference to a container.
 
-    \section3 Implicit sharing iterator problem
+    \section4 Implicit sharing iterator problem
 
     \l{Implicit sharing} has another consequence on STL-style
     iterators: you should avoid copying a container while
@@ -328,7 +351,7 @@
      The above example only shows a problem with QList, but
      the problem exists for all the implicitly shared Qt containers.
 
-    \section2 Java-Style Iterators
+    \section3 Java-Style Iterators
     \l{java-style-iterators}{Java-Style iterators} were introduced in Qt 4. Their API is modelled
     on Java's iterator classes.
     New code should should prefer \l{STL-Style Iterators}.