diff options
Diffstat (limited to 'src/corelib/kernel/qiterable.cpp')
| -rw-r--r-- | src/corelib/kernel/qiterable.cpp | 612 |
1 files changed, 612 insertions, 0 deletions
diff --git a/src/corelib/kernel/qiterable.cpp b/src/corelib/kernel/qiterable.cpp new file mode 100644 index 0000000000..a8c93fbc1c --- /dev/null +++ b/src/corelib/kernel/qiterable.cpp @@ -0,0 +1,612 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only + +#include <QtCore/qiterable.h> + +QT_BEGIN_NAMESPACE + +/*! + \class QBaseIterator + \inmodule QtCore + QBaseIterator forms the common base class for all iterators operating on + subclasses of QIterable. +*/ + +/*! + \fn template<class Container> QBaseIterator<Container>::QBaseIterator(const QIterable<Container> *iterable, void *iterator) + + \internal + Creates a const QBaseIterator from an \a iterable and an \a iterator. + */ + +/*! + \fn template<class Container> QBaseIterator<Container>::QBaseIterator(QIterable<Container> *iterable, void *iterator) + + \internal + Creates a non-const QBaseIterator from an \a iterable and an \a iterator. + */ + +/*! + \fn template<class Container> QBaseIterator<Container>::QBaseIterator(QBaseIterator<Container> &&other) + + \internal + Move-constructs a QBaseIterator from \a other, preserving its const-ness. + */ + +/*! + \fn template<class Container> QBaseIterator<Container>::QBaseIterator(const QBaseIterator<Container> &other) + + \internal + Copy-constructs a QBaseIterator from \a other, preserving its const-ness. + */ + +/*! + \fn template<class Container> QBaseIterator<Container>::~QBaseIterator() + + \internal + Destroys a QBaseIterator. + */ + +/*! + \fn template<class Container> QBaseIterator<Container> &QBaseIterator<Container>::operator=(const QBaseIterator<Container> &other) + + \internal + Copy-assigns a QBaseIterator from \a other, preserving its const-ness. + */ + +/*! + \fn template<class Container> void QBaseIterator<Container>::initIterator(const void *copy) + + \internal + Initializes the internal native iterator by duplicating \a copy, if given. + */ + +/*! + \fn template<class Container> void QBaseIterator<Container>::clearIterator() + + \internal + Destroys the internal native iterator. + */ + + +/*! + \fn QMetaContainer QBaseIterator<Container>::metaContainer() const + + \internal + Returns the meta sequence. + */ + +/*! + \fn template<class Container> QIterable *QBaseIterator<Container>::mutableIterable() const + + \internal + Returns a non-const pointer to the iterable, if the original iterable was + non-const. Otherwise returns nullptr. + */ + +/*! + \fn template<class Container> const QIterable *QBaseIterator<Container>::constIterable() const + + \internal + Returns a const pointer to the iterable. + */ + +/*! + \fn template<class Container> void *QBaseIterator<Container>::mutableIterator() + + Returns a non-const pointer to the internal native iterator. + */ + +/*! + \fn template<class Container> const void *QBaseIterator<Container>::constIterator() const + + Returns a const pointer to the internal native iterator. + */ + +/*! + \fn template<class Container> QBaseIterator &QBaseIterator<Container>::operator=(QBaseIterator<Container> &&other) + + \internal + Move-assigns a QBaseIterator from \a other, preserving its const-ness. + */ + +/*! + \class QIterator + \since 6.0 + \inmodule QtCore + \brief The QIterator is a template class that allows iteration over a container in a QVariant. + + A QIterator can only be created by a QIterable instance, and can be used + in a way similar to other stl-style iterators. Generally, QIterator should + not be used directly, but through its derived classes provided by + QSequentialIterable and QAssociativeIterable. + + \sa QIterable +*/ + +/*! + \fn template<class Container> QIterator<Container>::QIterator(QIterable<Container> *iterable, void *iterator) + + Creates an iterator from an \a iterable and a pointer to a native \a iterator. + */ + +/*! + \fn template<class Container> bool QIterator<Container>::operator==(const QIterator<Container> &other) const + + Returns \c true if \a other points to the same item as this + iterator; otherwise returns \c false. + + \sa operator!=() +*/ + +/*! + \fn template<class Container> bool QIterator<Container>::operator!=(const QIterator<Container> &other) const + + Returns \c true if \a other points to a different item than this + iterator; otherwise returns \c false. + + \sa operator==() +*/ + +/*! + \fn template<class Container> QIterator<Container> &QIterator<Container>::operator++() + + The prefix \c{++} operator (\c{++it}) advances the iterator to the + next item in the container and returns an iterator to the new current + item. + + Calling this function on QSequentialIterable::end() leads to undefined results. + + \sa operator--() +*/ + +/*! + \fn template<class Container> QIterator<Container> QIterator<Container>::operator++(int) + \overload + + The postfix \c{++} operator (\c{it++}) advances the iterator to the + next item in the container and returns an iterator to the previously + current item. +*/ + + +/*! + \fn template<class Container> QIterator<Container> &QIterator<Container>::operator--() + + The prefix \c{--} operator (\c{--it}) makes the preceding item + current and returns an iterator to the new current item. + + Calling this function on QSequentialIterable::begin() leads to undefined results. + + If the container in the QVariant does not support bi-directional iteration, calling this function + leads to undefined results. + + \sa operator++(), QIterable::canReverseIterate() +*/ + +/*! + \fn template<class Container> QIterator<Container> QIterator<Container>::operator--(int) + + \overload + + The postfix \c{--} operator (\c{it--}) makes the preceding item + current and returns an iterator to the previously current item. + + If the container in the QVariant does not support bi-directional iteration, calling this function + leads to undefined results. + + \sa QIterable::canReverseIterate() +*/ + +/*! + \fn template<class Container> QIterator<Container> &QIterator<Container>::operator+=(qsizetype j) + + Advances the iterator by \a j items. + + \sa operator-=(), operator+() +*/ + +/*! + \fn template<class Container> QIterator<Container> &QIterator<Container>::operator-=(qsizetype j) + + Makes the iterator go back by \a j items. + + If the container in the QVariant does not support bi-directional iteration, calling this function + leads to undefined results. + + \sa operator+=(), operator-(), QIterable::canReverseIterate() +*/ + +/*! + \fn template<class Container> QIterator<Container> QIterator<Container>::operator+(qsizetype j) const + + Returns an iterator to the item at \a j positions forward from + this iterator. + + \sa operator-(), operator+=() +*/ + +/*! + \fn template<class Container> QIterator<Container> QIterator<Container>::operator-(qsizetype j) const + + Returns an iterator to the item at \a j positions backward from + this iterator. + + If the container in the QVariant does not support bi-directional iteration, calling this function + leads to undefined results. + + \sa operator+(), operator-=(), QIterable::canReverseIterate() +*/ + +/*! + \fn template<class Container> qsizetype QIterator<Container>::operator-(const QIterator<Container> &j) const + \overload + + Returns the distance between the two iterators. + + \sa operator+(), operator-=(), QIterable::canReverseIterate() + */ + +/*! + \fn template <class Container> QIterator<Container> QIterator<Container>::operator+(qsizetype j, const QIterator<Container> &k) + + Returns an iterator to the item at \a j positions forward from iterator \a k. +*/ + +/*! + \struct QConstIterator + \since 6.0 + \inmodule QtCore + \brief The QConstIterator allows iteration over a container in a QVariant. + \sa QIterator, QIterable +*/ + +/*! + \fn template <class Container> QConstIterator<Container>::QConstIterator(const QIterable<Container> *iterable, void *iterator) + + Creates a QConstIterator to wrap \a iterator, operating on \a iterable. + */ + +/*! + \fn template<class Container> bool QConstIterator<Container>::operator==(const QConstIterator<Container> &other) const + + Returns \c true if \a other points to the same item as this + iterator; otherwise returns \c false. + + \sa operator!=() +*/ + +/*! + \fn template<class Container> bool QConstIterator<Container>::operator!=(const QConstIterator<Container> &other) const + + Returns \c true if \a other points to a different item than this + iterator; otherwise returns \c false. + + \sa operator==() +*/ + +/*! + \fn template<class Container> QConstIterator<Container> &QConstIterator<Container>::operator++() + + The prefix \c{++} operator (\c{++it}) advances the iterator to the + next item in the container and returns an iterator to the new current + item. + + Calling this function on QIterable<Container>::end() leads to undefined results. + + \sa operator--() +*/ + +/*! + \fn template<class Container> QConstIterator<Container> QConstIterator<Container>::operator++(int) + + \overload + + The postfix \c{++} operator (\c{it++}) advances the iterator to the + next item in the container and returns an iterator to the previously + current item. +*/ + +/*! + \fn template<class Container> QConstIterator<Container> &QConstIterator<Container>::operator--() + + The prefix \c{--} operator (\c{--it}) makes the preceding item + current and returns an iterator to the new current item. + + Calling this function on QIterable<Container>::begin() leads to undefined results. + + If the container in the QVariant does not support bi-directional iteration, calling this function + leads to undefined results. + + \sa operator++(), QIterable::canReverseIterate() +*/ + +/*! + \fn template<class Container> QConstIterator<Container> QConstIterator<Container>::operator--(int) + + \overload + + The postfix \c{--} operator (\c{it--}) makes the preceding item + current and returns an iterator to the previously current item. + + If the container in the QVariant does not support bi-directional iteration, calling this function + leads to undefined results. + + \sa QIterable::canReverseIterate() +*/ + +/*! + \fn template<class Container> QConstIterator<Container> &QConstIterator<Container>::operator+=(qsizetype j) + + Advances the iterator by \a j items. + + \sa operator-=(), operator+() +*/ + +/*! + \fn template<class Container> QConstIterator<Container> &QConstIterator<Container>::operator-=(qsizetype j) + + Makes the iterator go back by \a j items. + + If the container in the QVariant does not support bi-directional iteration, calling this function + leads to undefined results. + + \sa operator+=(), operator-(), QIterable::canReverseIterate() +*/ + +/*! + \fn template<class Container> QConstIterator<Container> QConstIterator<Container>::operator+(qsizetype j) const + + Returns an iterator to the item at \a j positions forward from + this iterator. + + \sa operator-(), operator+=() +*/ + +/*! + \fn template<class Container> QConstIterator<Container> QConstIterator<Container>::operator-(qsizetype j) const + + Returns an iterator to the item at \a j positions backward from + this iterator. + + If the container in the QVariant does not support bi-directional iteration, calling this function + leads to undefined results. + + \sa operator+(), operator-=(), QIterable::canReverseIterate() +*/ + +/*! + \fn template <class Container> qsizetype QConstIterator<Container>::operator-(const QConstIterator<Container> &j) const + + \overload + + Returns the distance between the two iterators. + + \sa operator+(), operator-=(), QIterable::canReverseIterate() + */ + +/*! + \class QIterable + \inmodule QtCore + \since 6.0 + \brief QIterable is a template class that is the base class for QSequentialIterable and QAssociativeIterable. +*/ + +/*! + \fn template <class Container> bool QIterable<Container>::canInputIterate() const + + Returns whether the container has an input iterator. This corresponds to + the std::input_iterator_tag iterator trait of the iterator and + const_iterator of the container. +*/ + +/*! + \fn template<class Container> bool QIterable<Container>::canForwardIterate() const + + Returns whether it is possible to iterate over the container in forward + direction. This corresponds to the std::forward_iterator_tag iterator trait + of the iterator and const_iterator of the container. +*/ + +/*! + \fn template<class Container> bool QIterable<Container>::canReverseIterate() const + + Returns whether it is possible to iterate over the container in reverse. This + corresponds to the std::bidirectional_iterator_tag iterator trait of the + const_iterator of the container. +*/ + +/*! + \fn template<class Container> bool QIterable<Container>::canRandomAccessIterate() const + + Returns whether it is possible to efficiently skip over multiple values + using and iterator. This corresponds to the std::random_access_iterator_tag + iterator trait of the iterator and const_iterator of the container. +*/ + +/*! + \fn template<class Container> QConstIterator<Container> QIterable<Container>::constBegin() const + + Returns a QConstIterator for the beginning of the container. This + can be used in stl-style iteration. + + \sa constEnd(), mutableBegin() +*/ + +/*! + \fn template<class Container> QConstIterator<Container> QIterable<Container>::constEnd() const + + Returns a Qterable::QConstIterator for the end of the container. This + can be used in stl-style iteration. + + \sa constBegin(), mutableEnd() +*/ + +/*! + \fn template<class Container> QIterator<Container> QIterable<Container>::mutableBegin() + + Returns a QIterator for the beginning of the container. This + can be used in stl-style iteration. + + \sa mutableEnd(), constBegin() +*/ + +/*! + \fn template<class Container> QIterator<Container> QIterable<Container>::mutableEnd() + + Returns a QSequentialIterable::iterator for the end of the container. This + can be used in stl-style iteration. + + \sa mutableBegin(), constEnd() +*/ + +/*! + \fn template<class Container> qsizetype QIterable<Container>::size() const + + Returns the number of values in the container. +*/ + +/*! + \class QTaggedIterator + \since 6.0 + \inmodule QtCore + \brief QTaggedIterator is a template class that wraps an iterator and exposes standard iterator traits. + + In order to use an iterator any of the standard algorithms, its iterator + traits need to be known. As QSequentialIterable can work with many different + kinds of containers, we cannot declare the traits in the iterator classes + themselves. A QTaggedIterator gives you a way to explicitly declare a trait for + a concrete instance of an iterator or QConstIterator. +*/ + +/*! + \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::QTaggedIterator(Iterator &&it) + + Constructs a QTaggedIterator from an iterator or QConstIterator \a it. Checks + whether the IteratorCategory passed as template argument matches the run + time capabilities of \a it; if there's no match, \a it is refused. +*/ + +/*! + \fn template<class Iterator, typename IteratorCategory> bool QTaggedIterator<Iterator, IteratorCategory>::operator==(const QTaggedIterator<Iterator, IteratorCategory> &other) const + + Returns \c true if \a other points to the same item as this + iterator; otherwise returns \c false. + + \sa operator!=() +*/ + +/*! + \fn template<class Iterator, typename IteratorCategory> bool QTaggedIterator<Iterator, IteratorCategory>::operator!=(const QTaggedIterator<Iterator, IteratorCategory> &other) const + + Returns \c true if \a other points to a different item than this + iterator; otherwise returns \c false. + + \sa operator==() +*/ + +/*! + \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> &QTaggedIterator<Iterator, IteratorCategory>::operator++() + + The prefix \c{++} operator (\c{++it}) advances the iterator to the + next item in the container and returns an iterator to the new current + item. + + Calling this function on QSequentialIterable::end() leads to undefined results. + + \sa operator--() +*/ + +/*! + \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator++(int) + \overload + + The postfix \c{++} operator (\c{it++}) advances the iterator to the + next item in the container and returns an iterator to the previously + current item. +*/ + + +/*! + \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> &QTaggedIterator<Iterator, IteratorCategory>::operator--() + + The prefix \c{--} operator (\c{--it}) makes the preceding item + current and returns an iterator to the new current item. + + Calling this function on QSequentialIterable::begin() leads to undefined results. + + If the container in the QVariant does not support bi-directional iteration, calling this function + leads to undefined results. + + \sa operator++(), QIterable::canReverseIterate() +*/ + +/*! + \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator--(int) + \overload + + The postfix \c{--} operator (\c{it--}) makes the preceding item + current and returns an iterator to the previously current item. + + If the container in the QVariant does not support bi-directional iteration, calling this function + leads to undefined results. + + \sa QIterable::canReverseIterate() +*/ + + +/*! + \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> &QTaggedIterator<Iterator, IteratorCategory>::operator+=(qsizetype j) + + Advances the iterator by \a j items. + + \sa operator-=(), operator+() +*/ + +/*! + \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> &QTaggedIterator<Iterator, IteratorCategory>::operator-=(qsizetype j) + + Makes the iterator go back by \a j items. + + If the container in the QVariant does not support bi-directional iteration, calling this function + leads to undefined results. + + \sa operator+=(), operator-(), QIterable::canReverseIterate() +*/ + +/*! + \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator+(qsizetype j) const + + Returns an iterator to the item at \a j positions forward from + this iterator. + + \sa operator-(), operator+=() +*/ + +/*! + \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator+(qsizetype j, const QTaggedIterator &k) + + Returns an iterator to the item at \a j positions forward from iterator \a k. +*/ + +/*! + \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator-(qsizetype j) const + + Returns an iterator to the item at \a j positions backward from + this iterator. + + If the container in the QVariant does not support bi-directional iteration, calling this function + leads to undefined results. + + \sa operator+(), operator-=(), QIterable::canReverseIterate() +*/ + +/*! + \fn template <class Iterator, typename IteratorCategory> qsizetype QTaggedIterator<Iterator, IteratorCategory>::operator-(const QTaggedIterator<Iterator, IteratorCategory> &j) const + + Returns the distance between this iterator and \a j. + + \sa operator+(), operator-=(), QIterable::canReverseIterate() +*/ + +QT_END_NAMESPACE |