diff options
Diffstat (limited to 'src/corelib/doc/src/containers.qdoc')
| -rw-r--r-- | src/corelib/doc/src/containers.qdoc | 83 |
1 files changed, 42 insertions, 41 deletions
diff --git a/src/corelib/doc/src/containers.qdoc b/src/corelib/doc/src/containers.qdoc index bed184de15..847be1bff6 100644 --- a/src/corelib/doc/src/containers.qdoc +++ b/src/corelib/doc/src/containers.qdoc @@ -39,7 +39,8 @@ \note Since Qt 5.14, range constructors are available for most of the container classes. QMultiMap is a notable exception. Their use is - encouraged in place of the various from/to methods. For example: + encouraged to replace of the various deprecated from/to methods of Qt 5. + For example: \snippet code/doc_src_containers.cpp 25 @@ -191,7 +192,30 @@ the C++ language doesn't specify any initialization; in those cases, Qt's containers automatically initialize the value to 0. - \section1 The Iterator Classes + \section1 Iterating over Containers + + \section2 Range-based for + + Range-based \c for should preferably be used for containers: + + \snippet code/doc_src_containers.cpp range_for + + Note that when using a Qt container in a non-const context, + \l{implicit sharing} may perform an undesired detach of the container. + To prevent this, use \c std::as_const(): + + \snippet code/doc_src_containers.cpp range_for_as_const + + For associative containers, this will loop over the values. + + \section2 Index-based + + For sequential containers that store their items contiguously in memory + (for example, QList), index-based iteration can be used: + + \snippet code/doc_src_containers.cpp index + + \section2 The Iterator Classes Iterators provide a uniform means to access items in a container. Qt's container classes provide two types of iterators: STL-style @@ -200,7 +224,7 @@ from \l{Implicit Sharing}{implicitly shared copies} due to a call to a non-const member function. - \section2 STL-Style Iterators + \section3 STL-Style Iterators STL-style iterators have been available since the release of Qt 2.0. They are compatible with Qt's and STL's \l{generic @@ -262,12 +286,10 @@ In the code snippets so far, we used the unary \c * operator to retrieve the item (of type QString) stored at a certain iterator - position, and we then called QString::toLower() on it. Most C++ - compilers also allow us to write \c{i->toLower()}, but some - don't. + position, and we then called QString::toLower() on it. - For read-only access, you can use const_iterator, \l{QList::constBegin}{constBegin()}, - and \l{QList::constEnd()}{constEnd()}. For example: + For read-only access, you can use const_iterator, \l{QList::cbegin}{cbegin()}, + and \l{QList::cend()}{cend()}. For example: \snippet code/doc_src_containers.cpp 12 @@ -315,7 +337,7 @@ This problem doesn't occur with functions that return a const or non-const reference to a container. - \section3 Implicit sharing iterator problem + \section4 Implicit sharing iterator problem \l{Implicit sharing} has another consequence on STL-style iterators: you should avoid copying a container while @@ -328,32 +350,11 @@ The above example only shows a problem with QList, but the problem exists for all the implicitly shared Qt containers. - \section2 Java-Style Iterators - \l{java-style-iterators}{Java-Style iterators} were introduced in Qt 4. Their API is modelled + \section3 Java-Style Iterators + \l{java-style-iterators}{Java-Style iterators} + are modelled on Java's iterator classes. - New code should should prefer \l{STL-Style Iterators}. - - \section1 Container keywords - - \target foreach - \section2 The foreach Keyword - \l{foreach-keyword}{The foreach keyword} is discouraged, new code should - prefer C++11 range-based loops. - - \target forever - \section2 The forever keyword. - In addition to \c foreach, Qt also provides a \c forever - pseudo-keyword for infinite loops: - - \snippet code/doc_src_containers.cpp 21 - - If you're worried about namespace pollution, you can disable - these macros by adding the following line to your \c .pro file: - - \snippet code/doc_src_containers.cpp 22 - - \note The alternative macros Q_FOREACH and Q_FOREVER remain defined - regardless. + New code should prefer \l{STL-Style Iterators}. \section1 Qt containers compared with std containers @@ -383,26 +384,26 @@ \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 + \li Similar to std::unordered_set<T>. Internally, \l{QSet} is implemented with a \l{QHash}. \row \li \l{QMap}<Key, T> - \li Similar to std::map<T>. + \li Similar to std::map<Key, T>. \row \li \l{QMultiMap}<Key, T> - \li Similar to std::multimap<T>. + \li Similar to std::multimap<Key, T>. \row \li \l{QHash}<Key, T> - \li Most similar to std::map<T>. + \li Most similar to std::unordered_map<Key, T>. \row \li \l{QMultiHash}<Key, T> - \li Most similar to std::multimap<T>. + \li Most similar to std::unordered_multimap<Key, T>. \endtable \section1 Qt containers and std algorithms - You can used Qt containers with functions from \c{#include <algorithm>}. + You can use Qt containers with functions from \c{#include <algorithm>}. \snippet code/doc_src_containers.cpp 26 @@ -410,7 +411,7 @@ Qt includes other template classes that resemble containers in some respects. These classes don't provide iterators and cannot - be used with the \c foreach keyword. + be used with the \l foreach keyword. \list \li QCache<Key, T> provides a cache to store objects of a certain |