foreach-keyword.qdoc

Go to the documentation of this file.

// 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
    \relates <QtGlobal>
 
    Defining this macro removes the availability of Qt's \c foreach
    loop.
 
    \sa QT_NO_KEYWORDS
*/