Implement key-value iterator

This patch implements an iterator that returns a pair containing both the
key and the value of an entry in QHash/QMap.

[ChangeLog][QtCore][Containers] Added an stl-like iterator to go through
QHash/QMap returning both the key and the value of the element pointed to.
That lets QHash/QMap interoperate better with stl's algorithms like
std::set_union.

Change-Id: Idbf8a8581510b3493648c34ab04c556de9fa4aa7
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

1 files changed, 67 insertions, 0 deletions

diff --git a/src/corelib/tools/qmap.cpp b/src/corelib/tools/qmap.cpp
index 94ed47f898..9738e2ed18 100644
--- a/src/corelib/tools/qmap.cpp
+++ b/src/corelib/tools/qmap.cpp
@@ -908,6 +908,61 @@ void QMapDataBase::freeData(QMapDataBase *d)
     \sa keyBegin(), lastKey()
 */
 
+
+/*! \fn QMap::key_value_iterator QMap::keyValueBegin()
+    \since 5.10
+
+    Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first entry
+    in the map.
+
+    \sa keyValueEnd()
+*/
+
+/*! \fn QMap::key_value_iterator QMap::keyValueEnd()
+    \since 5.10
+
+    Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
+    entry after the last entry in the map.
+
+    \sa keyValueBegin()
+*/
+
+/*! \fn QMap::const_key_value_iterator QMap::keyValueBegin() const
+    \since 5.10
+
+    Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
+    in the map.
+
+    \sa keyValueEnd()
+*/
+
+/*! \fn QMap::const_key_value_iterator QMap::constKeyValueBegin() const
+    \since 5.10
+
+    Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry
+    in the map.
+
+    \sa keyValueBegin()
+*/
+
+/*! \fn QMap::const_key_value_iterator QMap::keyValueEnd() const
+    \since 5.10
+
+    Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
+    entry after the last entry in the map.
+
+    \sa keyValueBegin()
+*/
+
+/*! \fn QMap::const_key_value_iterator QMap::constKeyValueEnd() const
+    \since 5.10
+
+    Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
+    entry after the last entry in the map.
+
+    \sa constKeyValueBegin()
+*/
+
 /*! \fn const Key &QMap::firstKey() const
     \since 5.2
 
@@ -1782,6 +1837,18 @@ void QMapDataBase::freeData(QMapDataBase *d)
     Returns the underlying const_iterator this key_iterator is based on.
 */
 
+/*! \typedef QMap::key_value_iterator
+    \inmodule QtCore
+    \since 5.10
+    \brief The QMap::key_value_iterator typedef provides an STL-style iterator for QMap and QMultiMap.
+
+    QMap::key_value_iterator is essentially the same as QMap::iterator
+    with the difference that operator*() returns a key/value pair instead of a
+    value.
+
+    \sa QKeyValueIterator
+*/
+
 /*! \fn QDataStream &operator<<(QDataStream &out, const QMap<Key, T> &map)
     \relates QMap