Doc: Modernize QHash iterator documentation

paulwicking · paulwicking · commit c068da1c7ccf · 2025-09-09T22:08:21.000Z
Promote STL-style iterators as the primary way to iterate over QHash.
Replace the detailed explanation with direct guidance to use
QHash::asKeyValueRange, and move Java-style iterators to a brief
compatibility note.

Update snippets to:
- Show C++17 structured bindings with
  std::as_const(hash).asKeyValueRange() (add &lt;utility&gt; header
  std::as_const).
- Add STL-style iterator example for manual control.
- Add example for modifying values in place.

This makes the docs clearer, const-correct, and aligned with modern C++
usage.

Fixes: QTBUG-139662
Pick-to: 6.10.0 6.10 6.9 6.8
Change-Id: Ifb9698b93ca53c3c6a7c82b0f1d393105cd62f35
Reviewed-by: Topi Reiniö &lt;topi.reinio@qt.io&gt;
diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp
@@ -6,6 +6,8 @@
 #include <iostream>
 #include <QDate>
 
+#include <utility>
+
 using namespace std;
 
 void examples()
@@ -61,11 +63,25 @@ void examples()
 
     {
         //! [8]
-        for (auto i = hash.cbegin(), end = hash.cend(); i != end; ++i)
-            cout << qPrintable(i.key()) << ": " << i.value() << endl;
+        for (const auto &[key, value] : std::as_const(hash).asKeyValueRange())
+            cout << qPrintable(key) << ": " << value << endl;
         //! [8]
     }
 
+    {
+        //! [qhash-iterator-stl-style]
+        for (auto it = hash.cbegin(); it != hash.cend(); ++it)
+            cout << qPrintable(it.key()) << ": " << it.value() << endl;
+        //! [qhash-iterator-stl-style]
+    }
+
+    {
+        //! [qhash-iterator-modify-values]
+        for (auto it = hash.begin(); it != hash.end(); ++it)
+            it.value() += 1;
+        //! [qhash-iterator-modify-values]
+    }
+
     {
         //! [9]
         hash.insert("plenty", 100);
diff --git a/src/corelib/tools/qhash.cpp b/src/corelib/tools/qhash.cpp
@@ -1529,18 +1529,23 @@ size_t qHash(long double key, size_t seed) noexcept
     QHash will not shrink automatically if items are removed from the
     table. To minimize the memory used by the hash, call squeeze().
 
-    If you want to navigate through all the (key, value) pairs stored
-    in a QHash, you can use an iterator. QHash provides both
-    \l{Java-style iterators} (QHashIterator and QMutableHashIterator)
-    and \l{STL-style iterators} (QHash::const_iterator and
-    QHash::iterator). Here's how to iterate over a QHash<QString,
-    int> using a Java-style iterator:
+    To iterate through all the (key, value) pairs stored in a
+    QHash, use \l {asKeyValueRange}():
 
-    \snippet code/src_corelib_tools_qhash.cpp 7
+    \snippet code/src_corelib_tools_qhash.cpp 8
 
-    Here's the same code, but using an STL-style iterator:
+    This function returns a range object that can be used with structured
+    bindings. For manual iterator control, you can also use traditional
+    \l{STL-style iterators} (QHash::const_iterator and QHash::iterator):
 
-    \snippet code/src_corelib_tools_qhash.cpp 8
+    \snippet code/src_corelib_tools_qhash.cpp qhash-iterator-stl-style
+
+    To modify values, use iterators:
+
+    \snippet code/src_corelib_tools_qhash.cpp qhash-iterator-modify-values
+
+    QHash also provides \l{Java-style iterators} (QHashIterator and
+    QMutableHashIterator) for compatibility.
 
     QHash is unordered, so an iterator's sequence cannot be assumed
     to be predictable. If ordering by key is required, use a QMap.
