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

/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/

#include <QtCore/qiterable.h>

QT_BEGIN_NAMESPACE

/*!
    \class QBaseIterator

    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 ++ 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 ++ 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 -- 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 -- 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

    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 ++ 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 ++ 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 -- 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 -- 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

    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 ++ 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 ++ 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 -- 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 -- 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