From 38968947151cf5572bec08bf654852dcb7888a04 Mon Sep 17 00:00:00 2001
From: Ole-Morten Duesund <olemd@odinprosjekt.no>
Date: Mon, 7 Dec 2020 15:47:28 +0100
Subject: [PATCH] Add sections about std containers and algorithms

Add section comparing Qt containers and std containers.

Add snippets showing use of std algorithms with Qt containers.

Task-number: QTBUG-86584
Change-Id: I1133a5214a5acd086c37658ca11ab205a19a489b
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 8183086513ae439220ae1facb1e93fc23b9a116b)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
---
 .../doc/snippets/code/doc_src_containers.cpp  | 21 ++++++++
 src/corelib/doc/src/containers.qdoc           | 51 +++++++++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/src/corelib/doc/snippets/code/doc_src_containers.cpp b/src/corelib/doc/snippets/code/doc_src_containers.cpp
index e5ccf0bb484..834056174f2 100644
--- a/src/corelib/doc/snippets/code/doc_src_containers.cpp
+++ b/src/corelib/doc/snippets/code/doc_src_containers.cpp
@@ -319,3 +319,24 @@ QSet<int> set(list.begin(), list.end());
     Will generate a QSet containing 1, 2, 3, 4, 5.
 */
 //! [25]
+
+//! [26]
+QList<int> list { 2, 3, 1 };
+
+std::sort(list.begin(), list.end());
+/*
+    Sort the list, now contains { 1, 2, 3 }
+*/
+
+std::reverse(list.begin(), list.end());
+/*
+    Reverse the list, now contains { 3, 2, 1 }
+*/
+
+int even_elements =
+        std::count_if(list.begin(), list.end(), [](int element) { return (element % 2 == 0); });
+/*
+    Count how many elements that are even numbers, 1
+*/
+
+//! [26]
diff --git a/src/corelib/doc/src/containers.qdoc b/src/corelib/doc/src/containers.qdoc
index c5b70c26758..5d4b9a2215b 100644
--- a/src/corelib/doc/src/containers.qdoc
+++ b/src/corelib/doc/src/containers.qdoc
@@ -379,6 +379,57 @@
     \note The alternative macros Q_FOREACH and Q_FOREVER remain defined
     regardless.
 
+    \section1 Qt containers compared with std containers
+
+    \table
+    \header \li Qt container \li Closest std container
+
+    \row \li \l{QList}<T>
+    \li Similar to std::vector<T>
+
+    \l{QList} and \l{QVector} were unified in Qt 6. Both
+    use the datamodel from QVector. QVector is now an alias to QList.
+
+    This means that QList is not implemented as a linked list, so if
+    you need constant time insert, delete, append or prepend,
+    consider \c std::list<T>. See \l{QList} for details.
+
+    \row \li \l{QVarLengthArray}<T, Prealloc>
+    \li Resembles a mix of std::array<T> and std::vector<T>.
+
+    For performance reasons, QVarLengthArray lives on the stack unless
+    resized. Resizing it automatically causes it to use the heap instead.
+
+    \row \li \l{QStack}<T>
+    \li Similar to std::stack<T>, inherits from \l{QList}.
+
+    \row \li \l{QQueue}<T>
+    \li Similar to std::queue<T>, inherits from \l{QList}.
+
+    \row \li \l{QSet}<T>
+    \li Similar to std::set<T>. Internally, \l{QSet} is implemented with a
+    \l{QHash}.
+
+    \row \li \l{QMap}<Key, T>
+    \li Similar to std::map<T>.
+
+    \row \li \l{QMultiMap}<Key, T>
+    \li Similar to std::multimap<T>.
+
+    \row \li \l{QHash}<Key, T>
+    \li Most similar to std::map<T>.
+
+    \row \li \l{QMultiHash}<Key, T>
+    \li Most similar to std::multimap<T>.
+
+    \endtable
+
+    \section1 Qt containers and std algorithms
+
+    You can used Qt containers with functions from \c{#include <algorithm>}.
+
+    \snippet code/doc_src_containers.cpp 26
+
     \section1 Other Container-Like Classes
 
     Qt includes other template classes that resemble containers in