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/qmetaassociation.h>
++ #include <QtCore/qmetatype.h>
++
++ QT_BEGIN_NAMESPACE
++
++ /*!
++ \class QMetaAssociation
++ \inmodule QtCore
++ \since 6.0
++ \brief The QMetaAssociation class allows type erased access to associative 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.
++
++ QMetaAssociation covers both, containers with mapped values such as QMap or
++ QHash, and containers that only hold keys such as QSet.
++
++ 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.
++
++ \sa QMetaContainer, QMetaSequence, QIterable, QIterator
++ */
++
++ /*!
++ \fn template<typename C> QMetaAssociation QMetaAssociation::fromContainer()
++ \since 6.0
++
++ Returns the QMetaAssociation corresponding to the type given as template parameter.
++ */
++
++ /*!
++ Returns the meta type for keys in the container.
++ */
++ QMetaType QMetaAssociation::keyMetaType() const
++ {
++ if (auto iface = d())
++ return QMetaType(iface->keyMetaType);
++ return QMetaType();
++ }
++
++ /*!
++ Returns the meta type for mapped values in the container.
++ */
++ QMetaType QMetaAssociation::mappedMetaType() const
++ {
++ if (auto iface = d())
++ return QMetaType(iface->mappedMetaType);
++ return QMetaType();
++ }
++
++ /*!
++ \fn bool QMetaAssociation::canInsertKey() const
++
++ Returns \c true if keys can be added to the container using \l insertKey(),
++ otherwise returns \c false.
++
++ \sa insertKey()
++ */
++
++ /*!
++ \fn void QMetaAssociation::insertKey(void *container, const void *key) const
++
++ Inserts the \a key into the \a container if possible. If the container has
++ mapped values a default-create mapped value is associated with the \a key.
++
++ \sa canInsertKey()
++ */
++
++ /*!
++ \fn bool QMetaAssociation::canRemoveKey() const
++
++ Returns \c true if keys can be removed from the container using
++ \l removeKey(), otherwise returns \c false.
++
++ \sa removeKey()
++ */
++
++ /*!
++ \fn void QMetaAssociation::removeKey(void *container, const void *key) const
++
++ Removes the \a key and its associated mapped value from the \a container if
++ possible.
++
++ \sa canRemoveKey()
++ */
++
++ /*!
++ \fn bool QMetaAssociation::canContainsKey() const
++
++ Returns \c true if the container can be queried for keys using
++ \l containsKey(), otherwise returns \c false.
++ */
++
++ /*!
++ \fn bool QMetaAssociation::containsKey(const void *container, const void *key) const
++
++ Returns \c true if the \a container can be queried for keys and contains the
++ \a key, otherwise returns \c false.
++
++ \sa canContainsKey()
++ */
++
++ /*!
++ \fn bool QMetaAssociation::canGetMappedAtKey() const
++
++ Returns \c true if the container can be queried for values using
++ \l mappedAtKey(), otherwise returns \c false.
++ */
++
++ /*!
++ \fn void QMetaAssociation::mappedAtKey(const void *container, const void *key, void *mapped) const
++
++ Retrieves the mapped value associated with the \a key in the \a container
++ and places it in the memory location pointed to by \a mapped, if that is
++ possible.
++
++ \sa canGetMappedAtKey()
++ */
++
++ /*!
++ \fn bool QMetaAssociation::canSetMappedAtKey() const
++
++ Returns \c true if mapped values can be modified in the container using
++ \l setMappedAtKey(), otherwise returns \c false.
++
++ \sa setMappedAtKey()
++ */
++
++ /*!
++ \fn void QMetaAssociation::setMappedAtKey(void *container, const void *key, const void *mapped) const
++
++ Overwrites the value associated with the \a key in the \a container using
++ the \a mapped value passed as argument if that is possible.
++
++ \sa canSetMappedAtKey()
++ */
++
++ /*!
++ \fn bool QMetaAssociation::canGetKeyAtIterator() const
++
++ Returns \c true if a key can be retrieved from a non-const iterator using
++ \l keyAtIterator(), otherwise returns \c false.
++
++ \sa keyAtIterator()
++ */
++
++ /*!
++ \fn void QMetaAssociation::keyAtIterator(const void *iterator, void *key) const
++
++ Retrieves the key pointed to by the non-const \a iterator and stores it
++ in the memory location pointed to by \a key, if possible.
++
++ \sa canGetKeyAtIterator(), begin(), end(), createIteratorAtKey()
++ */
++
++ /*!
++ \fn bool QMetaAssociation::canGetKeyAtConstIterator() const
++
++ Returns \c true if a key can be retrieved from a const iterator using
++ \l keyAtConstIterator(), otherwise returns \c false.
++
++ \sa keyAtConstIterator()
++ */
++
++ /*!
++ \fn void QMetaAssociation::keyAtConstIterator(const void *iterator, void *key) const
++
++ Retrieves the key pointed to by the const \a iterator and stores it
++ in the memory location pointed to by \a key, if possible.
++
++ \sa canGetKeyAtConstIterator(), constBegin(), constEnd(), createConstIteratorAtKey()
++ */
++
++ /*!
++ \fn bool QMetaAssociation::canGetMappedAtIterator() const
++
++ Returns \c true if a mapped value can be retrieved from a non-const
++ iterator using \l mappedAtIterator(), otherwise returns \c false.
++
++ \sa mappedAtIterator()
++ */
++
++ /*!
++ \fn void QMetaAssociation::mappedAtIterator(const void *iterator, void *mapped) const
++
++ Retrieves the mapped value pointed to by the non-const \a iterator and
++ stores it in the memory location pointed to by \a mapped, if possible.
++
++ \sa canGetMappedAtIterator(), begin(), end(), createIteratorAtKey()
++ */
++
++ /*!
++ \fn bool QMetaAssociation::canGetMappedAtConstIterator() const
++
++ Returns \c true if a mapped value can be retrieved from a const iterator
++ using \l mappedAtConstIterator(), otherwise returns \c false.
++
++ \sa mappedAtConstIterator()
++ */
++
++ /*!
++ \fn void QMetaAssociation::mappedAtConstIterator(const void *iterator, void *mapped) const
++
++ Retrieves the mapped value pointed to by the const \a iterator and
++ stores it in the memory location pointed to by \a mapped, if possible.
++
++ \sa canGetMappedAtConstIterator(), constBegin(), constEnd(), createConstIteratorAtKey()
++ */
++
++ /*!
++ \fn bool QMetaAssociation::canSetMappedAtIterator() const
++
++ Returns \c true if a mapped value can be set via a non-const iterator using
++ \l setMappedAtIterator(), otherwise returns \c false.
++
++ \sa setMappedAtIterator()
++ */
++
++ /*!
++ \fn void QMetaAssociation::setMappedAtIterator(const void *iterator, const void *mapped) const
++
++ Writes the \a mapped value to the container location pointed to by the
++ non-const \a iterator, if possible.
++
++ \sa canSetMappedAtIterator(), begin(), end(), createIteratorAtKey()
++ */
++
++ /*!
++ \fn bool QMetaAssociation::canCreateIteratorAtKey() const
++
++ Returns \c true if an iterator pointing to an entry in the container can be
++ created using \l createIteratorAtKey(), otherwise returns false.
++
++ \sa createIteratorAtKey()
++ */
++
++ /*!
++ \fn void *QMetaAssociation::createIteratorAtKey(void *container, const void *key) const
++
++ Returns a non-const iterator pointing to the entry of \a key in the
++ \a container, if possible. If the entry doesn't exist, creates a non-const
++ iterator pointing to the end of the \a container. If no non-const iterator
++ can be created, returns \c nullptr.
++
++ The non-const iterator has to be destroyed using destroyIterator().
++
++ \sa canCreateIteratorAtKey(), begin(), end(), destroyIterator()
++ */
++
++ /*!
++ \fn bool QMetaAssociation::canCreateConstIteratorAtKey() const
++
++ Returns \c true if a const iterator pointing to an entry in the container
++ can be created using \l createConstIteratorAtKey(), otherwise returns false.
++ */
++
++ /*!
++ \fn void *QMetaAssociation::createConstIteratorAtKey(const void *container, const void *key) const
++
++ Returns a const iterator pointing to the entry of \a key in the
++ \a container, if possible. If the entry doesn't exist, creates a const
++ iterator pointing to the end of the \a container. If no const iterator can
++ be created, returns \c nullptr.
++
++ The const iterator has to be destroyed using destroyConstIterator().
++
++ \sa canCreateConstIteratorAtKey(), constBegin(), constEnd(), destroyConstIterator()
++ */
++
++ /*!
++ \fn bool QMetaAssociation::operator==(const QMetaAssociation &lhs, const QMetaAssociation &rhs)
++
++ Returns \c true if the QMetaAssociation \a lhs represents the same container type
++ as the QMetaAssociation \a rhs, otherwise returns \c false.
++ */
++ /*!
++ \fn bool QMetaAssociation::operator!=(const QMetaAssociation &lhs, const QMetaAssociation &rhs)
++
++ Returns \c true if the QMetaAssociation \a lhs represents a different container
++ type than the QMetaAssociation \a rhs, otherwise returns \c false.
++ */
++
++ /*!
++ \class QMetaAssociation::Iterable
++ \inherits QIterable
++ \since 6.11
++ \inmodule QtCore
++ \brief QMetaAssociation::Iterable is an iterable interface for an associative container in a QVariant.
++
++ This class allows several methods of accessing the elements of an
++ associative container held within a QVariant. An instance of
++ QMetaAssociation::Iterable can be extracted from a QVariant if it can be
++ converted to a QVariantHash or QVariantMap or if a custom mutable view has
++ been registered.
++
++ \snippet code/src_corelib_kernel_qvariant.cpp 10
++
++ The container itself is not copied before iterating over it.
++
++ \sa QVariant
++ */
++
++ /*!
++ \typealias QMetaAssociation::Iterable::RandomAccessIterator
++ Exposes an iterator using std::random_access_iterator_tag.
++ */
++
++ /*!
++ \typealias QMetaAssociation::Iterable::BidirectionalIterator
++ Exposes an iterator using std::bidirectional_iterator_tag.
++ */
++
++ /*!
++ \typealias QMetaAssociation::Iterable::ForwardIterator
++ Exposes an iterator using std::forward_iterator_tag.
++ */
++
++ /*!
++ \typealias QMetaAssociation::Iterable::InputIterator
++ Exposes an iterator using std::input_iterator_tag.
++ */
++
++ /*!
++ \typealias QMetaAssociation::Iterable::RandomAccessConstIterator
++ Exposes a const_iterator using std::random_access_iterator_tag.
++ */
++
++ /*!
++ \typealias QMetaAssociation::Iterable::BidirectionalConstIterator
++ Exposes a const_iterator using std::bidirectional_iterator_tag.
++ */
++
++ /*!
++ \typealias QMetaAssociation::Iterable::ForwardConstIterator
++ Exposes a const_iterator using std::forward_iterator_tag.
++ */
++
++ /*!
++ \typealias QMetaAssociation::Iterable::InputConstIterator
++ Exposes a const_iterator using std::input_iterator_tag.
++ */
++
++ /*!
++ \class QMetaAssociation::Iterable::ConstIterator
++ \inherits QConstIterator
++ \since 6.11
++ \inmodule QtCore
++ \brief QMetaAssociation::Iterable::ConstIterator allows iteration over a container in a QVariant.
++
++ A QMetaAssociation::Iterable::ConstIterator can only be created by a
++ QMetaAssociation::Iterable instance, and can be used in a way similar to
++ other stl-style iterators.
++
++ \snippet code/src_corelib_kernel_qvariant.cpp 10
++
++ \sa QMetaAssociation::Iterable
++ */
++
++ /*!
++ \class QMetaAssociation::Iterable::Iterator
++ \inherits QIterator
++ \since 6.11
++ \inmodule QtCore
++ \brief The QMetaAssociation::Iterable::Iterator allows iteration over a container in a QVariant.
++
++ A QMetaAssociation::Iterable::Iterator can only be created by a
++ QMetaAssociation::Iterable instance, and can be used in a way similar to
++ other stl-style iterators.
++
++ \sa QMetaAssociation::Iterable
++ */
++
++ /*!
++ \fn QMetaAssociation::Iterable::ConstIterator QMetaAssociation::Iterable::find(const QVariant &key) const
++ Retrieves a ConstIterator pointing to the element at the given \a key, or
++ the end of the container if that key does not exist. If the \a key isn't
++ convertible to the expected type, the end of the container is returned.
++ */
++
++ /*!
++ \fn QMetaAssociation::Iterable::Iterator QMetaAssociation::Iterable::mutableFind(const QVariant &key)
++ Retrieves an iterator pointing to the element at the given \a key, or
++ the end of the container if that key does not exist. If the \a key isn't
++ convertible to the expected type, the end of the container is returned.
++ */
++
++ /*!
++ \fn bool QMetaAssociation::Iterable::containsKey(const QVariant &key) const
++ Returns \c true if the container has an entry with the given \a key, or
++ \c false otherwise. If the \a key isn't convertible to the expected type,
++ \c false is returned.
++ */
++
++ /*!
++ \fn void QMetaAssociation::Iterable::insertKey(const QVariant &key)
++ Inserts a new entry with the given \a key, or resets the mapped value of
++ any existing entry with the given \a key to the default constructed
++ mapped value. The \a key is coerced to the expected type: If it isn't
++ convertible, a default value is inserted.
++ */
++
++ /*!
++ \fn void QMetaAssociation::Iterable::removeKey(const QVariant &key)
++ Removes the entry with the given \a key from the container. The \a key is
++ coerced to the expected type: If it isn't convertible, the default value
++ is removed.
++ */
++
++ /*!
++ \fn QVariant QMetaAssociation::Iterable::value(const QVariant &key) const
++ Retrieves the mapped value at the given \a key, or a QVariant of a
++ default-constructed instance of the mapped type, if the key does not
++ exist. If the \a key is not convertible to the key type, the mapped value
++ associated with the default-constructed key is returned.
++ */
++
++ /*!
++ \fn void QMetaAssociation::Iterable::setValue(const QVariant &key, const QVariant &mapped)
++ Sets the mapped value associated with \a key to \a mapped, if possible.
++ Inserts a new entry if none exists yet, for the given \a key. If the
++ \a key is not convertible to the key type, the value for the
++ default-constructed key type is overwritten.
++ */
++
++
++ /*!
++ \fn QVariant QMetaAssociation::Iterable::Iterator::key() const
++ Returns the key this iterator points to.
++ */
++
++ /*!
++ \fn QVariant::Reference<QMetaAssociation::Iterable::Iterator> QMetaAssociation::Iterable::Iterator::value() const
++ Returns the mapped value this iterator points to. If the container does not
++ provide a mapped value (for example a set), returns an invalid
++ QVariant::Reference.
++ */
++
++ /*!
++ \fn QVariant::Reference<QMetaAssociation::Iterable::Iterator> QMetaAssociation::Iterable::Iterator::operator*() const
++ Returns the current item, converted to a QVariant::Reference. The resulting
++ QVariant::Reference resolves to the mapped value if there is one, or to the
++ key value if not.
++ */
++
++ /*!
++ \fn QVariant::Pointer<QMetaAssociation::Iterable::Iterator> QMetaAssociation::Iterable::Iterator::operator->() const
++ Returns the current item, converted to a QVariant::Pointer. The resulting
++ QVariant::Pointer resolves to the mapped value if there is one, or to the
++ key value if not.
++ */
++
++ /*!
++ \fn QVariant QMetaAssociation::Iterable::ConstIterator::key() const
++ Returns the key this iterator points to.
++ */
++
++ /*!
++ \fn QVariant QMetaAssociation::Iterable::ConstIterator::value() const
++ Returns the mapped value this iterator points to, or an invalid QVariant if
++ there is no mapped value.
++ */
++
++ /*!
++ \fn QVariant QMetaAssociation::Iterable::ConstIterator::operator*() const
++ Returns the current item, converted to a QVariant. The returned value is the
++ mapped value at the current iterator if there is one, or otherwise the key.
++ */
++
++ /*!
++ \fn QVariant::ConstPointer<QMetaAssociation::Iterable::ConstIterator> QMetaAssociation::Iterable::ConstIterator::operator->() const
++ Returns the current item, converted to a QVariant::ConstPointer. The
++ QVariant::ConstPointer will resolve to the mapped value at the current
++ iterator if there is one, or otherwise the key.
++ */
++
++ QT_END_NAMESPACE