1 files changed, 87 insertions, 0 deletions
diff --git a/src/corelib/doc/src/foreach-keyword.qdoc b/src/corelib/doc/src/foreach-keyword.qdoc
new file mode 100644
index 0000000000..b3a4482528
--- /dev/null
+++ b/src/corelib/doc/src/foreach-keyword.qdoc
@@ -0,0 +1,87 @@
+// Copyright (C) 2020 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \page foreach-keyword.html
+    \title Qt's foreach Keyword
+    \ingroup groups
+    \ingroup qt-basic-concepts
+
+    \brief Qt's foreach keyword.
+
+    \tableofcontents
+
+    \target foreach-keyword
+    \section1 The foreach Keyword
+
+    \note The foreach keyword was introduced before the C++11 range-based loops
+    existed. New code should prefer C++11 range-based loops.
+
+    The \c foreach keyword is a Qt-specific addition to the C++ language,
+    and is implemented using the preprocessor.
+
+    Its syntax is: \c foreach (\e variable, \e container) \e
+    statement. For example, here's how to use \c foreach to iterate
+    over a QList<QString>:
+
+    \snippet code/doc_src_containers.cpp 15
+
+    The \c foreach code is significantly shorter than the equivalent
+    code that uses iterators:
+
+    \snippet code/doc_src_containers.cpp 16
+
+    Unless the data type contains a comma (e.g., \c{std::pair<int,
+    int>}), the variable used for iteration can be defined within the
+    \c foreach statement:
+
+    \snippet code/doc_src_containers.cpp 17
+
+    And like any other C++ loop construct, you can use braces around
+    the body of a \c foreach loop, and you can use \c break to leave
+    the loop:
+
+    \snippet code/doc_src_containers.cpp 18
+
+    With QMap and QHash, \c foreach accesses the value component of
+    the (key, value) pairs automatically, so you should not call
+    values() on the container (it would generate an unnecessary copy,
+    see below). If you want to iterate over both the keys and the
+    values, you can use iterators (which are faster), or you can
+    obtain the keys, and use them to get the values too:
+
+    \snippet code/doc_src_containers.cpp 19
+
+    For a multi-valued map:
+
+    \snippet code/doc_src_containers.cpp 20
+
+    Qt automatically takes a copy of the container when it enters a
+    \c foreach loop. If you modify the container as you are
+    iterating, that won't affect the loop. (If you do not modify the
+    container, the copy still takes place, but thanks to \l{implicit
+    sharing} copying a container is very fast.)
+
+    Since foreach creates a copy of the container, using a non-const
+    reference for the variable does not allow you to modify the original
+    container. It only affects the copy, which is probably not what you
+    want.
+
+    An alternative to Qt's \c foreach loop is the range-based \c for that is
+    part of C++11 and newer. However, keep in mind that the range-based
+    \c for might force a Qt container to \l{Implicit Sharing}{detach}, whereas
+    \c foreach would not. But using \c foreach always copies the container,
+    which is usually not cheap for STL containers. If in doubt, prefer
+    \c foreach for Qt containers, and range based \c for for STL ones.
+
+    You can remove the availability of the Qt's \c foreach loop by
+    defining the \c{QT_NO_FOREACH} macro.
+*/
+
+/*!
+    \macro QT_NO_FOREACH
+    \since 6.0
+
+    Defining this macro removes the availability of Qt's \c foreach
+    loop.
+*/