Revision control
++ // Copyright (C) 2025 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
++ // Qt-Security score:significant reason:default
++
++ #include <QtCore/qmetasequence.h>
++ #include <QtCore/qmetatype.h>
++
++ QT_BEGIN_NAMESPACE
++
++ /*!
++ \class QMetaSequence
++ \inmodule QtCore
++ \since 6.0
++ \brief The QMetaSequence class allows type erased access to sequential containers.
++
++ \ingroup objectmodel
++
++ \compares equality
++
++ The class provides a number of primitive container operations, using void*
++ as operands. This way, you can manipulate a generic container retrieved from
++ a Variant without knowing its type.
++
++ The void* arguments to the various methods are typically created by using
++ a \l QVariant of the respective container or value type, and calling
++ its \l QVariant::data() or \l QVariant::constData() methods. However, you
++ can also pass plain pointers to objects of the container or value type.
++
++ Iterator invalidation follows the rules given by the underlying containers
++ and is not expressed in the API. Therefore, for a truly generic container,
++ any iterators should be considered invalid after any write operation.
++ */
++
++ /*!
++ \fn template<typename C> QMetaSequence QMetaSequence::fromContainer()
++ \since 6.0
++
++ Returns the QMetaSequence corresponding to the type given as template parameter.
++ */
++
++ /*!
++ Returns the meta type for values stored in the container.
++ */
++ QMetaType QMetaSequence::valueMetaType() const
++ {
++ if (auto iface = d())
++ return QMetaType(iface->valueMetaType);
++ return QMetaType();
++ }
++
++ /*!
++ Returns \c true if the underlying container is sortable, otherwise returns
++ \c false. A container is considered sortable if values added to it are
++ placed in a defined location. Inserting into or adding to a sortable
++ container will always succeed. Inserting into or adding to an unsortable
++ container may not succeed, for example if the container is a QSet that
++ already contains the value being inserted.
++
++ \sa addValue(), insertValueAtIterator(), canAddValueAtBegin(),
++ canAddValueAtEnd(), canRemoveValueAtBegin(), canRemoveValueAtEnd()
++ */
++ bool QMetaSequence::isSortable() const
++ {
++ if (auto iface = d()) {
++ return (iface->addRemoveCapabilities
++ & (QtMetaContainerPrivate::CanAddAtBegin | QtMetaContainerPrivate::CanAddAtEnd))
++ && (iface->addRemoveCapabilities
++ & (QtMetaContainerPrivate::CanRemoveAtBegin
++ | QtMetaContainerPrivate::CanRemoveAtEnd));
++ }
++ return false;
++ }
++
++ /*!
++ Returns \c true if values added using \l addValue() can be placed at the
++ beginning of the container, otherwise returns \c false.
++
++ \sa addValueAtBegin(), canAddValueAtEnd()
++ */
++ bool QMetaSequence::canAddValueAtBegin() const
++ {
++ if (auto iface = d()) {
++ return iface->addValueFn
++ && iface->addRemoveCapabilities & QtMetaContainerPrivate::CanAddAtBegin;
++ }
++ return false;
++ }
++
++ /*!
++ Adds \a value to the beginning of \a container if possible. If
++ \l canAddValueAtBegin() returns \c false, the \a value is not added.
++
++ \sa canAddValueAtBegin(), isSortable(), removeValueAtBegin()
++ */
++ void QMetaSequence::addValueAtBegin(void *container, const void *value) const
++ {
++ if (canAddValueAtBegin())
++ d()->addValueFn(container, value, QtMetaContainerPrivate::QMetaSequenceInterface::AtBegin);
++ }
++
++ /*!
++ Returns \c true if values can be removed from the beginning of the container
++ using \l removeValue(), otherwise returns \c false.
++
++ \sa removeValueAtBegin(), canRemoveValueAtEnd()
++ */
++ bool QMetaSequence::canRemoveValueAtBegin() const
++ {
++ if (auto iface = d()) {
++ return iface->removeValueFn
++ && iface->addRemoveCapabilities & QtMetaContainerPrivate::CanRemoveAtBegin;
++ }
++ return false;
++ }
++
++ /*!
++ Removes a value from the beginning of \a container if possible. If
++ \l canRemoveValueAtBegin() returns \c false, the value is not removed.
++
++ \sa canRemoveValueAtBegin(), isSortable(), addValueAtBegin()
++ */
++ void QMetaSequence::removeValueAtBegin(void *container) const
++ {
++ if (canRemoveValueAtBegin())
++ d()->removeValueFn(container, QtMetaContainerPrivate::QMetaSequenceInterface::AtBegin);
++ }
++
++ /*!
++ Returns \c true if values added using \l addValue() can be placed at the
++ end of the container, otherwise returns \c false.
++
++ \sa addValueAtEnd(), canAddValueAtBegin()
++ */
++ bool QMetaSequence::canAddValueAtEnd() const
++ {
++ if (auto iface = d()) {
++ return iface->addValueFn
++ && iface->addRemoveCapabilities & QtMetaContainerPrivate::CanAddAtEnd;
++ }
++ return false;
++ }
++
++ /*!
++ Adds \a value to the end of \a container if possible. If
++ \l canAddValueAtEnd() returns \c false, the \a value is not added.
++
++ \sa canAddValueAtEnd(), isSortable(), removeValueAtEnd()
++ */
++ void QMetaSequence::addValueAtEnd(void *container, const void *value) const
++ {
++ if (canAddValueAtEnd())
++ d()->addValueFn(container, value, QtMetaContainerPrivate::QMetaSequenceInterface::AtEnd);
++ }
++
++ /*!
++ Returns \c true if values can be removed from the end of the container
++ using \l removeValue(), otherwise returns \c false.
++
++ \sa removeValueAtEnd(), canRemoveValueAtBegin()
++ */
++ bool QMetaSequence::canRemoveValueAtEnd() const
++ {
++ if (auto iface = d()) {
++ return iface->removeValueFn
++ && iface->addRemoveCapabilities & QtMetaContainerPrivate::CanRemoveAtEnd;
++ }
++ return false;
++ }
++
++ /*!
++ Removes a value from the end of \a container if possible. If
++ \l canRemoveValueAtEnd() returns \c false, the value is not removed.
++
++ \sa canRemoveValueAtEnd(), isSortable(), addValueAtEnd()
++ */
++ void QMetaSequence::removeValueAtEnd(void *container) const
++ {
++ if (canRemoveValueAtEnd())
++ d()->removeValueFn(container, QtMetaContainerPrivate::QMetaSequenceInterface::AtEnd);
++ }
++
++ /*!
++ Returns \c true if values can be retrieved from the container by index,
++ otherwise \c false.
++
++ \sa valueAtIndex()
++ */
++ bool QMetaSequence::canGetValueAtIndex() const
++ {
++ if (auto iface = d())
++ return iface->valueAtIndexFn;
++ return false;
++ }
++
++ /*!
++ Retrieves the value at \a index in the \a container and places it in the
++ memory location pointed to by \a result, if that is possible.
++
++ \sa canGetValueAtIndex()
++ */
++ void QMetaSequence::valueAtIndex(const void *container, qsizetype index, void *result) const
++ {
++ if (canGetValueAtIndex())
++ d()->valueAtIndexFn(container, index, result);
++ }
++
++ /*!
++ Returns \c true if a value can be written to the container by index,
++ otherwise \c false.
++
++ \sa setValueAtIndex()
++ */
++ bool QMetaSequence::canSetValueAtIndex() const
++ {
++ if (auto iface = d())
++ return iface->setValueAtIndexFn;
++ return false;
++ }
++
++ /*!
++ Overwrites the value at \a index in the \a container using the \a value
++ passed as parameter if that is possible.
++
++ \sa canSetValueAtIndex()
++ */
++ void QMetaSequence::setValueAtIndex(void *container, qsizetype index, const void *value) const
++ {
++ if (canSetValueAtIndex())
++ d()->setValueAtIndexFn(container, index, value);
++ }
++
++ /*!
++ Returns \c true if values can be added to the container, \c false
++ otherwise.
++
++ \sa addValue(), isSortable()
++ */
++ bool QMetaSequence::canAddValue() const
++ {
++ if (auto iface = d())
++ return iface->addValueFn;
++ return false;
++ }
++
++ /*!
++ Adds \a value to the \a container if possible. If \l canAddValue()
++ returns \c false, the \a value is not added. Else, if
++ \l canAddValueAtEnd() returns \c true, the \a value is added
++ to the end of the \a container. Else, if
++ \l canAddValueAtBegin() returns \c true, the \a value is added to
++ the beginning of the container. Else, the value is added in an unspecified
++ place or not at all. The latter is the case for adding values to an
++ unordered container, for example \l QSet.
++
++ \sa canAddValue(), canAddValueAtBegin(),
++ canAddValueAtEnd(), isSortable(), removeValue()
++ */
++ void QMetaSequence::addValue(void *container, const void *value) const
++ {
++ if (canAddValue()) {
++ d()->addValueFn(container, value,
++ QtMetaContainerPrivate::QMetaSequenceInterface::Unspecified);
++ }
++ }
++
++ /*!
++ Returns \c true if values can be removed from the container, \c false
++ otherwise.
++
++ \sa removeValue(), isSortable()
++ */
++ bool QMetaSequence::canRemoveValue() const
++ {
++ if (auto iface = d())
++ return iface->removeValueFn;
++ return false;
++ }
++
++ /*!
++ Removes a value from the \a container if possible. If
++ \l canRemoveValue() returns \c false, no value is removed. Else, if
++ \l canRemoveValueAtEnd() returns \c true, the last value in
++ the \a container is removed. Else, if \l canRemoveValueAtBegin()
++ returns \c true, the first value in the \a container is removed. Else,
++ an unspecified value or nothing is removed.
++
++ \sa canRemoveValue(), canRemoveValueAtBegin(),
++ canRemoveValueAtEnd(), isSortable(), addValue()
++ */
++ void QMetaSequence::removeValue(void *container) const
++ {
++ if (canRemoveValue()) {
++ d()->removeValueFn(container,
++ QtMetaContainerPrivate::QMetaSequenceInterface::Unspecified);
++ }
++ }
++
++
++ /*!
++ Returns \c true if the underlying container can retrieve the value pointed
++ to by a non-const iterator, \c false otherwise.
++
++ \sa hasIterator(), valueAtIterator()
++ */
++ bool QMetaSequence::canGetValueAtIterator() const
++ {
++ if (auto iface = d())
++ return iface->valueAtIteratorFn;
++ return false;
++ }
++
++ /*!
++ Retrieves the value pointed to by the non-const \a iterator and stores it
++ in the memory location pointed to by \a result, if possible.
++
++ \sa canGetValueAtIterator(), begin(), end()
++ */
++ void QMetaSequence::valueAtIterator(const void *iterator, void *result) const
++ {
++ if (canGetValueAtIterator())
++ d()->valueAtIteratorFn(iterator, result);
++ }
++
++ /*!
++ Returns \c true if the underlying container can write to the value pointed
++ to by a non-const iterator, \c false otherwise.
++
++ \sa hasIterator(), setValueAtIterator()
++ */
++ bool QMetaSequence::canSetValueAtIterator() const
++ {
++ if (auto iface = d())
++ return iface->setValueAtIteratorFn;
++ return false;
++ }
++
++ /*!
++ Writes \a value to the value pointed to by the non-const \a iterator, if
++ possible.
++
++ \sa canSetValueAtIterator(), begin(), end()
++ */
++ void QMetaSequence::setValueAtIterator(const void *iterator, const void *value) const
++ {
++ if (canSetValueAtIterator())
++ d()->setValueAtIteratorFn(iterator, value);
++ }
++
++ /*!
++ Returns \c true if the underlying container can insert a new value, taking
++ the location pointed to by a non-const iterator into account.
++
++ \sa hasIterator(), insertValueAtIterator()
++ */
++ bool QMetaSequence::canInsertValueAtIterator() const
++ {
++ if (auto iface = d())
++ return iface->insertValueAtIteratorFn;
++ return false;
++ }
++
++ /*!
++ Inserts \a value into the \a container, if possible, taking the non-const
++ \a iterator into account. If \l canInsertValueAtIterator() returns
++ \c false, the \a value is not inserted. Else if \l isSortable() returns
++ \c true, the value is inserted before the value pointed to by
++ \a iterator. Else, the \a value is inserted at an unspecified place or not
++ at all. In the latter case, the \a iterator is taken as a hint. If it points
++ to the correct place for the \a value, the operation may be faster than a
++ \l addValue() without iterator.
++
++ \sa canInsertValueAtIterator(), isSortable(), begin(), end()
++ */
++ void QMetaSequence::insertValueAtIterator(void *container, const void *iterator,
++ const void *value) const
++ {
++ if (canInsertValueAtIterator())
++ d()->insertValueAtIteratorFn(container, iterator, value);
++ }
++
++ /*!
++ Returns \c true if the value pointed to by a non-const iterator can be
++ erased, \c false otherwise.
++
++ \sa hasIterator(), eraseValueAtIterator()
++ */
++ bool QMetaSequence::canEraseValueAtIterator() const
++ {
++ if (auto iface = d())
++ return iface->eraseValueAtIteratorFn;
++ return false;
++ }
++
++ /*!
++ Erases the value pointed to by the non-const \a iterator from the
++ \a container, if possible.
++
++ \sa canEraseValueAtIterator(), begin(), end()
++ */
++ void QMetaSequence::eraseValueAtIterator(void *container, const void *iterator) const
++ {
++ if (canEraseValueAtIterator())
++ d()->eraseValueAtIteratorFn(container, iterator);
++ }
++
++ /*!
++ Returns \c true if a range between two iterators can be erased from the
++ container, \c false otherwise.
++ */
++ bool QMetaSequence::canEraseRangeAtIterator() const
++ {
++ if (auto iface = d())
++ return iface->eraseRangeAtIteratorFn;
++ return false;
++ }
++
++ /*!
++ Erases the range of values between the iterators \a iterator1 and
++ \a iterator2 from the \a container, if possible.
++
++ \sa canEraseValueAtIterator(), begin(), end()
++ */
++ void QMetaSequence::eraseRangeAtIterator(void *container, const void *iterator1,
++ const void *iterator2) const
++ {
++ if (canEraseRangeAtIterator())
++ d()->eraseRangeAtIteratorFn(container, iterator1, iterator2);
++ }
++
++
++ /*!
++ Returns \c true if the underlying container can retrieve the value pointed
++ to by a const iterator, \c false otherwise.
++
++ \sa hasConstIterator(), valueAtConstIterator()
++ */
++ bool QMetaSequence::canGetValueAtConstIterator() const
++ {
++ if (auto iface = d())
++ return iface->valueAtConstIteratorFn;
++ return false;
++ }
++
++ /*!
++ Retrieves the value pointed to by the const \a iterator and stores it
++ in the memory location pointed to by \a result, if possible.
++
++ \sa canGetValueAtConstIterator(), constBegin(), constEnd()
++ */
++ void QMetaSequence::valueAtConstIterator(const void *iterator, void *result) const
++ {
++ if (canGetValueAtConstIterator())
++ d()->valueAtConstIteratorFn(iterator, result);
++ }
++
++ /*!
++ \fn bool QMetaSequence::operator==(const QMetaSequence &lhs, const QMetaSequence &rhs)
++ \since 6.0
++
++ Returns \c true if the QMetaSequence \a lhs represents the same container type
++ as the QMetaSequence \a rhs, otherwise returns \c false.
++ */
++
++ /*!
++ \fn bool QMetaSequence::operator!=(const QMetaSequence &lhs, const QMetaSequence &rhs)
++ \since 6.0
++
++ Returns \c true if the QMetaSequence \a lhs represents a different container
++ type than the QMetaSequence \a rhs, otherwise returns \c false.
++ */
++
++ /*!
++ \class QMetaSequence::Iterable
++ \inherits QIterable
++ \since 6.11
++ \inmodule QtCore
++ \brief The QMetaSequence::Iterable class is an iterable interface for a container in a QVariant.
++
++ This class allows several methods of accessing the values of a container
++ held within a QVariant. An instance of QMetaSequence::Iterable can be
++ extracted from a QVariant if it can be converted to a QVariantList, or if
++ the container it contains is registered using
++ Q_DECLARE_SEQUENTIAL_CONTAINER_METATYPE. Most sequential containers found
++ in Qt and some found in the C++ standard library are automatically
++ registered.
++
++ \snippet code/src_corelib_kernel_qvariant.cpp 9
++
++ The container itself is not copied before iterating over it.
++
++ \sa QVariant
++ */
++
++ /*!
++ \typealias QMetaSequence::Iterable::RandomAccessIterator
++ Exposes an iterator using std::random_access_iterator_tag.
++ */
++
++ /*!
++ \typealias QMetaSequence::Iterable::BidirectionalIterator
++ Exposes an iterator using std::bidirectional_iterator_tag.
++ */
++
++ /*!
++ \typealias QMetaSequence::Iterable::ForwardIterator
++ Exposes an iterator using std::forward_iterator_tag.
++ */
++
++ /*!
++ \typealias QMetaSequence::Iterable::InputIterator
++ Exposes an iterator using std::input_iterator_tag.
++ */
++
++ /*!
++ \typealias QMetaSequence::Iterable::RandomAccessConstIterator
++ Exposes a const_iterator using std::random_access_iterator_tag.
++ */
++
++ /*!
++ \typealias QMetaSequence::Iterable::BidirectionalConstIterator
++ Exposes a const_iterator using std::bidirectional_iterator_tag.
++ */
++
++ /*!
++ \typealias QMetaSequence::Iterable::ForwardConstIterator
++ Exposes a const_iterator using std::forward_iterator_tag.
++ */
++
++ /*!
++ \typealias QMetaSequence::Iterable::InputConstIterator
++ Exposes a const_iterator using std::input_iterator_tag.
++ */
++
++ /*!
++ \fn QVariant QMetaSequence::Iterable::at(qsizetype idx) const
++ Returns the value at position \a idx in the container.
++
++ \note If the underlying container does not provide a native way to retrieve
++ an element at an index, this method will synthesize the access using
++ iterators. This behavior is deprecated and will be removed in a future
++ version of Qt.
++ */
++
++ /*!
++ \fn void QMetaSequence::Iterable::setAt(qsizetype idx, const QVariant &value)
++ Sets the element at position \a idx in the container to \a value.
++ */
++
++ /*!
++ \class QMetaSequence::Iterable::ConstIterator
++ \inmodule QtCore
++ \inherits QConstIterator
++ \since 6.11
++ \brief QMetaSequence::Iterable::ConstIterator allows iteration over a container in a QVariant.
++
++ A QMetaSequence::Iterable::ConstIterator can only be created by a
++ QMetaSequence::Iterable instance, and can be used in a way similar to other
++ stl-style iterators.
++
++ \snippet code/src_corelib_kernel_qvariant.cpp 9
++ */
++
++ /*!
++ \class QMetaSequence::Iterable::Iterator
++ \inmodule QtCore
++ \inherits QIterator
++ \since 6.11
++ \brief QMetaSequence::Iterable::Iterator allows iteration over a container in a QVariant.
++
++ A QMetaSequence::Iterable::Iterator can only be created by a QMetaSequence::Iterable
++ instance, and can be used in a way similar to other stl-style iterators.
++ */
++
++ /*!
++ \fn QVariant::Reference<QMetaSequence::Iterable::Iterator> QMetaSequence::Iterable::Iterator::operator*() const
++ Returns the current item, converted to a QVariant::Reference.
++ */
++
++ /*!
++ \fn QVariant::Pointer<QMetaSequence::Iterable::Iterator> QMetaSequence::Iterable::Iterator::operator->() const
++ Returns the current item, converted to a QVariant::Pointer.
++ */
++
++ /*!
++ \fn QVariant::Reference<QMetaSequence::Iterable::Iterator> QMetaSequence::Iterable::Iterator::operator[](qsizetype n) const
++ Returns the item offset from the current one by \a n, converted to a
++ QVariant::Reference.
++ */
++
++ /*!
++ \fn QVariant QMetaSequence::Iterable::ConstIterator::operator*() const
++ Returns the current item, converted to a QVariant.
++ */
++
++ /*!
++ \fn QVariant::ConstPointer<QMetaSequence::Iterable::ConstIterator> QMetaSequence::Iterable::ConstIterator::operator->() const
++ Returns the current item, converted to a QVariant::ConstPointer.
++ */
++
++ /*!
++ \fn QVariant QMetaSequence::Iterable::ConstIterator::operator[](qsizetype n) const
++ Returns the item offset from the current one by \a n, converted to a
++ QVariant.
++ */
++
++ QT_END_NAMESPACE