path: root/src/corelib/kernel/qiterable.cpp

// 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::constEnd() 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::constBegin() 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::constEnd() 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::constBegin() 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