Revision control
Copy as Markdown
// Copyright (C) 2020 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*! \class QKeyValueIterator
\inmodule QtCore
\since 5.10
\brief Iterator over the key/value pairs of an associative container.
The QKeyValueIterator class provides an STL-style iterator for returning
key/value pairs from associative containers like QHash and QMap. The
template parameter \a Key specifies the key type, \a T specifies the value
type, \a Iterator is the underlying iterator type, and \a Traits specifies
the iterator traits. It supports the same API as the STL associative
containers, i.e. getting a key/value pair when iterating through the
container.
This will allow for better interoperability between QMap, QHash and friends
and STL-style algorithms.
\warning Iterators on implicitly shared containers do not work
exactly like STL-iterators. You should avoid copying a container
while iterators are active on that container. For more information,
read \l{Implicit sharing iterator problem}.
*/
/*! \typedef QKeyValueIterator::iterator_category
\internal
*/
/*! \typedef QKeyValueIterator::difference_type
\internal
*/
/*! \typedef QKeyValueIterator::value_type
\internal
*/
/*! \struct QKeyValueIterator::pointer
\internal
*/
/*! \typedef QKeyValueIterator::reference
\internal
*/
/*! \fn template<typename Key, typename T, class Iterator, class Traits> QKeyValueIterator<Key, T, Iterator, Traits>::QKeyValueIterator()
Constructs a default QKeyValueIterator.
*/
/*! \fn template<typename Key, typename T, class Iterator, class Traits> QKeyValueIterator<Key, T, Iterator, Traits>::QKeyValueIterator(Iterator o)
Constructs a QKeyValueIterator on top of \a o.
*/
/*! \fn template<typename Key, typename T, class Iterator, class Traits> std::pair<Key, T> QKeyValueIterator<Key, T, Iterator, Traits>::operator*() const
Returns the current entry as a pair.
*/
/*! \fn template<typename Key, typename T, class Iterator, class Traits> pointer QKeyValueIterator<Key, T, Iterator,Traits>::operator->() const
Returns the current entry as a pointer-like object to the pair.
\since 5.15
\sa operator*()
*/
/*! \fn template<typename Key, typename T, class Iterator, class Traits> bool QKeyValueIterator<Key, T, Iterator, Traits>::operator==(QKeyValueIterator<Key, T, Iterator, Traits> lhs, QKeyValueIterator<Key, T, Iterator, Traits> rhs)
Returns \c true if \a rhs points to the same item as \a lhs otherwise returns
\c false.
\sa operator!=()
*/
/*! \fn template<typename Key, typename T, class Iterator, class Traits> bool QKeyValueIterator<Key, T, Iterator, Traits>::operator!=(QKeyValueIterator<Key, T, Iterator, Traits> lhs, QKeyValueIterator<Key, T, Iterator, Traits> rhs)
Returns \c true if \a rhs points to a different item than \a lhs otherwise
returns \c false.
\sa operator==()
*/
/*!
\fn template<typename Key, typename T, class Iterator, class Traits> QKeyValueIterator &QKeyValueIterator<Key, T, Iterator, Traits>::operator++()
The prefix \c{++} operator (\c{++i}) advances the iterator to the
next item in the container and returns the iterator.
\note Advancing the iterator past its container's \l{iterator-end}{end()} constitutes
undefined behavior.
\sa operator--()
*/
/*! \fn template<typename Key, typename T, class Iterator, class Traits> QKeyValueIterator QKeyValueIterator<Key, T, Iterator, Traits>::operator++(int)
\overload
The postfix \c{++} operator (\c{i++}) advances the iterator to the
next item in the container and returns the iterator's prior value.
\note Advancing the iterator past its container's \l{iterator-end}{end()} constitutes
undefined behavior.
*/
/*! \fn template<typename Key, typename T, class Iterator, class Traits> QKeyValueIterator &QKeyValueIterator<Key, T, Iterator, Traits>::operator--()
The prefix c{--} operator (\c{--i}) backs the iterator up to the previous item
in the container and returns the iterator.
\note Backing up an iterator to before its container's \l{iterator-begin}{begin()} constitutes
undefined behavior.
\sa operator++()
*/
/*! \fn template<typename Key, typename T, class Iterator, class Traits> QKeyValueIterator QKeyValueIterator<Key, T, Iterator, Traits>::operator--(int)
\overload
The postfix c{--} operator (\c{i--}) backs the iterator up to the previous item
in the container and returns the iterator's prior value.
\note Backing up an iterator to before its container's \l{iterator-begin}{begin()} constitutes
undefined behavior.
*/
/*! \fn template<typename Key, typename T, class Iterator, class Traits> Iterator QKeyValueIterator<Key, T, Iterator, Traits>::base() const
Returns the underlying iterator this QKeyValueIterator is based on.
*/
/*!
\class QListIterator
\inmodule QtCore
\ingroup java-style-iterators
\brief The QListIterator class provides a Java-style const iterator for QList and QQueue.
QList has both \l{Java-style iterators} and \l{STL-style
iterators}. STL-style iterators are more efficient and should
be preferred. The template parameter \a T specifies the type of
the items stored in the list.
An alternative to using iterators is to use index positions. Most
QList member functions take an index as their first parameter,
making it possible to access, modify, and remove items without
using iterators.
QListIterator\<T\> allows you to iterate over a QList\<T\>,
a QQueue\<T\> or a QStack\<T\>. If you want to modify the list
as you iterate over it, use QMutableListIterator\<T\> instead.
The QListIterator constructor takes a QList as argument. After
construction, the iterator is located at the very beginning of
the list (before the first item). Here's how to iterate over all
the elements sequentially:
\snippet code/doc_src_qiterator.cpp 0
The next() function returns the next item in the list and
advances the iterator. Unlike STL-style iterators, Java-style
iterators point \e between items rather than directly \e at
items. The first call to next() advances the iterator to the
position between the first and second item, and returns the first
item; the second call to next() advances the iterator to the
position between the second and third item, and returns the second
item; and so on.
\image javaiterators1.svg {Iterator positions between items A, B, C, D}
Here's how to iterate over the elements in reverse order:
\snippet code/doc_src_qiterator.cpp 1
If you want to find all occurrences of a particular value, use
findNext() or findPrevious() in a loop.
Multiple iterators can be used on the same list. If the list is
modified while a QListIterator is active, the QListIterator will
continue iterating over the original list, ignoring the modified
copy.
\sa QMutableListIterator, QList::const_iterator
*/
/*!
\class QSetIterator
\inmodule QtCore
\ingroup java-style-iterators
\brief The QSetIterator class provides a Java-style const iterator for QSet.
QSet has both \l{Java-style iterators} and \l{STL-style
iterators}. STL-style iterators are more efficient and should
be preferred. The template parameter \a T specifies the type of
the items stored in the set.
QSetIterator\<T\> allows you to iterate over a QSet\<T\>. If you
want to modify the set as you iterate over it, use
QMutableSetIterator\<T\> instead.
The constructor takes a QSet as argument. After construction, the
iterator is located at the very beginning of the set (before
the first item). Here's how to iterate over all the elements
sequentially:
\snippet code/doc_src_qiterator.cpp 6
The next() function returns the next item in the set and
advances the iterator. Unlike STL-style iterators, Java-style
iterators point \e between items rather than directly \e at
items. The first call to next() advances the iterator to the
position between the first and second item, and returns the first
item; the second call to next() advances the iterator to the
position between the second and third item, returning the second
item; and so on.
\image javaiterators1.svg {Iterator positions between items A, B, C, D}
If you want to find all occurrences of a particular value, use
findNext() in a loop.
Multiple iterators can be used on the same set. If the set
is modified while a QSetIterator is active, the QSetIterator
will continue iterating over the original set, ignoring the
modified copy.
\sa QMutableSetIterator, QSet::const_iterator
*/
/*!
\class QMutableListIterator
\inmodule QtCore
\brief The QMutableListIterator class provides a Java-style non-const iterator for QList, QQueue and QStack.
QList has both \l{Java-style iterators} and \l{STL-style
iterators}. STL-style iterators are more efficient and should
be preferred. The template parameter \a T specifies the type of
the items stored in the list.
An alternative to using iterators is to use index positions. Most
QList member functions take an index as their first parameter,
making it possible to access, insert, and remove items without
using iterators.
QMutableListIterator\<T\> allows you to iterate over a QList\<T\>
(or a QQueue\<T\>) and modify the list. If you don't want to
modify the list (or have a const QList), use the slightly faster
QListIterator\<T\> instead.
The QMutableListIterator constructor takes a QList as argument.
After construction, the iterator is located at the very beginning
of the list (before the first item). Here's how to iterate over
all the elements sequentially:
\snippet code/doc_src_qiterator.cpp 8
The next() function returns the next item in the list and
advances the iterator. Unlike STL-style iterators, Java-style
iterators point \e between items rather than directly \e at
items. The first call to next() advances the iterator to the
position between the first and second item, and returns the first
item; the second call to next() advances the iterator to the
position between the second and third item, returning the second
item; and so on.
\image javaiterators1.svg {Iterator positions between items A, B, C, D}
Here's how to iterate over the elements in reverse order:
\snippet code/doc_src_qiterator.cpp 9
If you want to find all occurrences of a particular value, use
findNext() or findPrevious() in a loop.
If you want to remove items as you iterate over the list, use
remove(). If you want to modify the value of an item, use
setValue(). If you want to insert a new item in the list, use
insert().
Example:
\snippet code/doc_src_qiterator.cpp 10
The example traverses a list, replacing negative numbers with
their absolute values, and eliminating zeroes.
Only one mutable iterator can be active on a given list at any
time. Furthermore, no changes should be done directly to the list
while the iterator is active (as opposed to through the
iterator), since this could invalidate the iterator and lead to
undefined behavior.
\sa QListIterator, QList::iterator
*/
/*!
\class QMutableSetIterator
\inmodule QtCore
\ingroup java-style-iterators
\since 4.2
\brief The QMutableSetIterator class provides a Java-style non-const iterator for QSet.
QSet has both \l{Java-style iterators} and \l{STL-style
iterators}. STL-style iterators are more efficient and should
be preferred. The template parameter \a T specifies the type of
the items stored in the set.
QMutableSetIterator\<T\> allows you to iterate over a QSet\<T\>
and remove items from the set as you iterate. If you don't want
to modify the set (or have a const QSet), use the slightly faster
QSetIterator\<T\> instead.
The QMutableSetIterator constructor takes a QSet as argument.
After construction, the iterator is located at the very beginning
of the set (before the first item). Here's how to iterate over
all the elements sequentially:
\snippet code/doc_src_qiterator.cpp 17
The next() function returns the next item in the set and
advances the iterator. Unlike STL-style iterators, Java-style
iterators point \e between items rather than directly \e at
items. The first call to next() advances the iterator to the
position between the first and second item, and returns the first
item; the second call to next() advances the iterator to the
position between the second and third item, returning the second
item; and so on.
\image javaiterators1.svg {Iterator positions between items A, B, C, D}
If you want to remove items as you iterate over the set, use
remove().
Only one mutable iterator can be active on a given set at any
time. Furthermore, no changes should be done directly to the set
while the iterator is active (as opposed to through the
iterator), since this could invalidate the iterator and lead to
undefined behavior.
\sa QSetIterator, QSet::iterator
*/
/*!
\fn template <class T> QListIterator<T>::QListIterator(const QList<T> &list)
\fn template <class T> QMutableListIterator<T>::QMutableListIterator(QList<T> &list)
Constructs an iterator for traversing \a list. The iterator is
set to be at the front of the list (before the first item).
\sa operator=()
*/
/*!
\fn template <class T> QSetIterator<T>::QSetIterator(const QSet<T> &set)
\fn template <class T> QMutableSetIterator<T>::QMutableSetIterator(QSet<T> &set)
Constructs an iterator for traversing \a set. The iterator is
set to be at the front of the set (before the first item).
\sa operator=()
*/
/*! \fn template <class T> QMutableListIterator &QMutableListIterator<T>::operator=(QList<T> &list)
\fn template <class T> QListIterator &QListIterator<T>::operator=(const QList<T> &list)
Makes the iterator operate on \a list. The iterator is set to be
at the front of the list (before the first item).
\sa toFront(), toBack()
*/
/*! \fn template <class T> QSetIterator &QSetIterator<T>::operator=(const QSet<T> &set)
\fn template <class T> QMutableSetIterator &QMutableSetIterator<T>::operator=(QSet<T> &set)
Makes the iterator operate on \a set. The iterator is set to be
at the front of the set (before the first item).
\sa toFront(), toBack()
*/
/*! \fn template <class T> void QListIterator<T>::toFront()
\fn template <class T> void QSetIterator<T>::toFront()
\fn template <class T> void QMutableListIterator<T>::toFront()
\fn template <class T> void QMutableSetIterator<T>::toFront()
Moves the iterator to the front of the container (before the
first item).
\sa toBack(), next()
*/
/*! \fn template <class T> void QListIterator<T>::toBack()
\fn template <class T> void QMutableListIterator<T>::toBack()
//! [toBack]
Moves the iterator to the back of the container (after the last
item).
//! [toBack]
\sa toFront(), previous()
*/
/*! \fn template <class T> void QSetIterator<T>::toBack()
\include qiterator.qdoc toBack
\sa toFront()
*/
/*! \fn template <class T> void QMutableSetIterator<T>::toBack()
Moves the iterator to the back of the container (after the last
item).
\sa toFront()
*/
/*! \fn template <class T> bool QListIterator<T>::hasNext() const
\fn template <class T> bool QMutableListIterator<T>::hasNext() const
//! [hasNext]
Returns \c true if there is at least one item ahead of the iterator,
i.e. the iterator is \e not at the back of the container;
otherwise returns \c false.
//! [hasNext]
\sa hasPrevious(), next()
*/
/*! \fn template <class T> bool QSetIterator<T>::hasNext() const
\include qiterator.qdoc hasNext
\sa next()
*/
/*! \fn template <class T> bool QMutableSetIterator<T>::hasNext() const
Returns \c true if there is at least one item ahead of the iterator,
i.e. the iterator is \e not at the back of the container;
otherwise returns \c false.
\sa next()
*/
/*! \fn template <class T> const T &QListIterator<T>::next()
//! [next]
Returns the next item and advances the iterator by one position.
Calling this function on an iterator located at the back of the
container leads to undefined results.
//! [next]
\sa hasNext(), peekNext(), previous()
*/
/*!
\fn template <class T> const T &QSetIterator<T>::next()
\include qiterator.qdoc next
\sa hasNext(), peekNext()
*/
/* \fn template <class T> const T &QMutableSetIterator<T>::next()
Returns the next item and advances the iterator by one position.
Calling this function on an iterator located at the back of the
container leads to undefined results.
\sa hasNext(), peekNext()
*/
/*! \fn template <class T> const T &QMutableSetIterator<T>::next()
Returns the next item and advances the iterator by one position.
Calling this function on an iterator located at the back of the
container leads to undefined results.
\sa hasNext(), peekNext()
*/
/*! \fn template <class T> T &QMutableListIterator<T>::next()
Returns a reference to the next item, and advances the iterator
by one position.
Calling this function on an iterator located at the back of the
container leads to undefined results.
\sa hasNext(), peekNext(), previous()
*/
/*! \fn template <class T> const T &QListIterator<T>::peekNext() const
//! [peekNext]
Returns the next item without moving the iterator.
Calling this function on an iterator located at the back of the
container leads to undefined results.
//! [peekNext]
\sa hasNext(), next(), peekPrevious()
*/
/*!
\fn template <class T> const T &QSetIterator<T>::peekNext() const
\include qiterator.qdoc peekNext
\sa hasNext(), next()
*/
/*!
\fn template <class T> const T &QMutableSetIterator<T>::peekNext() const
Returns the next item without moving the iterator.
Calling this function on an iterator located at the back of the
container leads to undefined results.
\sa hasNext(), next()
*/
/*! \fn template <class T> T &QMutableListIterator<T>::peekNext() const
Returns a reference to the next item, without moving the iterator.
Calling this function on an iterator located at the back of the
container leads to undefined results.
\sa hasNext(), next(), peekPrevious()
*/
/*! \fn template <class T> bool QListIterator<T>::hasPrevious() const
\fn template <class T> bool QMutableListIterator<T>::hasPrevious() const
Returns \c true if there is at least one item behind the iterator,
i.e. the iterator is \e not at the front of the container;
otherwise returns \c false.
\sa hasNext(), previous()
*/
/*! \fn template <class T> const T &QListIterator<T>::previous()
Returns the previous item and moves the iterator back by one
position.
Calling this function on an iterator located at the front of the
container leads to undefined results.
\sa hasPrevious(), peekPrevious(), next()
*/
/*! \fn template <class T> T &QMutableListIterator<T>::previous()
Returns a reference to the previous item and moves the iterator
back by one position.
Calling this function on an iterator located at the front of the
container leads to undefined results.
\sa hasPrevious(), peekPrevious(), next()
*/
/*! \fn template <class T> const T &QListIterator<T>::peekPrevious() const
Returns the previous item without moving the iterator.
Calling this function on an iterator located at the front of the
container leads to undefined results.
\sa hasPrevious(), previous(), peekNext()
*/
/*! \fn template <class T> T &QMutableListIterator<T>::peekPrevious() const
Returns a reference to the previous item, without moving the iterator.
Calling this function on an iterator located at the front of the
container leads to undefined results.
\sa hasPrevious(), previous(), peekNext()
*/
/*!
\fn template <class T> bool QMutableSetIterator<T>::findNext(const T &value)
Searches for \a value starting from the current iterator position
forward. Returns \c true if \a value is found; otherwise returns \c false.
After the call, if \a value was found, the iterator is positioned
just after the matching item; otherwise, the iterator is
positioned at the back of the container.
*/
/*! \fn template <class T> bool QListIterator<T>::findNext(const T &value)
\fn template <class T> bool QMutableListIterator<T>::findNext(const T &value)
//! [findNext]
Searches for \a value starting from the current iterator position
forward. Returns \c true if \a value is found; otherwise returns \c false.
After the call, if \a value was found, the iterator is positioned
just after the matching item; otherwise, the iterator is
positioned at the back of the container.
//! [findNext]
\sa findPrevious()
*/
/*! \fn template <class T> bool QSetIterator<T>::findNext(const T &value)
\include qiterator.qdoc findNext
*/
/*! \fn template <class T> bool QListIterator<T>::findPrevious(const T &value)
\fn template <class T> bool QMutableListIterator<T>::findPrevious(const T &value)
Searches for \a value starting from the current iterator position
backward. Returns \c true if \a value is found; otherwise returns
false.
After the call, if \a value was found, the iterator is positioned
just before the matching item; otherwise, the iterator is
positioned at the front of the container.
\sa findNext()
*/
/*! \fn template <class T> void QMutableListIterator<T>::remove()
Removes the last item that was jumped over using one of the
traversal functions (next(), previous(), findNext(), findPrevious()).
Example:
\snippet code/doc_src_qiterator.cpp 19
\sa insert(), setValue()
*/
/*! \fn template <class T> void QMutableSetIterator<T>::remove()
Removes the last item that was jumped over using one of the
traversal functions (next(), findNext()).
Example:
\snippet code/doc_src_qiterator.cpp 22
\sa value()
*/
/*! \fn template <class T> void QMutableListIterator<T>::setValue(const T &value) const
Replaces the value of the last item that was jumped over using
one of the traversal functions with \a value.
The traversal functions are next(), previous(), findNext(), and
findPrevious().
Example:
\snippet code/doc_src_qiterator.cpp 23
\sa value(), remove(), insert()
*/
/*! \fn template <class T> const T &QMutableListIterator<T>::value() const
Returns the value of the last item that was jumped over using one
of the traversal functions (next(), previous(), findNext(),
findPrevious()).
After a call to next() or findNext(), value() is equivalent to
peekPrevious(). After a call to previous() or findPrevious(), value() is
equivalent to peekNext().
*/
/*! \fn template <class T> const T &QMutableSetIterator<T>::value() const
Returns the value of the last item that was jumped over using
next() or findNext().
*/
/*!
\fn template <class T> T &QMutableListIterator<T>::value()
\overload
Returns a non-const reference to the value of the last item that
was jumped over using one of the traversal functions.
*/
/*! \fn template <class T> void QMutableListIterator<T>::insert(const T &value)
Inserts \a value at the current iterator position. After the
call, the iterator is located just after the inserted item.
\sa remove(), setValue()
*/
/*!
\class QMapIterator
\inmodule QtCore
\ingroup java-style-iterators
\brief The QMapIterator class provides a Java-style const iterator for QMap.
QMap has both \l{Java-style iterators} and \l{STL-style
iterators}. STL-style iterators are more efficient and should
be preferred. The template parameter \a Key specifies the map's
key type, and \a T specifies the value type.
QMapIterator\<Key, T\> allows you to iterate over a QMap.
If you want to modify the map as you iterate over
it, use QMutableMapIterator instead.
The QMapIterator constructor takes a QMap as argument. After
construction, the iterator is located at the very beginning of
the map (before the first item). Here's how to iterate over all
the elements sequentially:
\snippet code/doc_src_qiterator.cpp 26
The next() function returns the next item in the map and
advances the iterator. The key() and value() functions return the
key and value of the last item that was jumped over.
Unlike STL-style iterators, Java-style iterators point \e between
items rather than directly \e at items. The first call to next()
advances the iterator to the position between the first and
second item, and returns the first item; the second call to
next() advances the iterator to the position between the second
and third item; and so on.
\image javaiterators1.svg {Iterator positions between items A, B, C, D}
Here's how to iterate over the elements in reverse order:
\snippet code/doc_src_qiterator.cpp 27
If you want to find all occurrences of a particular value, use
findNext() or findPrevious() in a loop. For example:
\snippet code/doc_src_qiterator.cpp 28
Multiple iterators can be used on the same map. If the map is
modified while a QMapIterator is active, the QMapIterator will
continue iterating over the original map, ignoring the modified
copy.
\sa QMutableMapIterator, QMap::const_iterator
*/
/*!
\class QMultiMapIterator
\inmodule QtCore
\ingroup java-style-iterators
\brief The QMultiMapIterator class provides a Java-style const iterator for QMultiMap.
QMultiMap has both \l{Java-style iterators} and \l{STL-style
iterators}. STL-style iterators are more efficient and should
be preferred. The template parameter \a Key specifies the map's
key type, and \a T specifies the value type.
QMultiMapIterator\<Key, T\> allows you to iterate over a QMultiMap.
If you want to modify the map as you iterate over
it, use QMutableMultiMapIterator instead.
The QMultiMapIterator constructor takes a QMultiMap as argument. After
construction, the iterator is located at the very beginning of
the map (before the first item). Here's how to iterate over all
the elements sequentially:
\snippet code/doc_src_qiterator.cpp 26multi
The next() function returns the next item in the map and
advances the iterator. The key() and value() functions return the
key and value of the last item that was jumped over.
Unlike STL-style iterators, Java-style iterators point \e between
items rather than directly \e at items. The first call to next()
advances the iterator to the position between the first and
second item, and returns the first item; the second call to
next() advances the iterator to the position between the second
and third item; and so on.
\image javaiterators1.svg {Iterator positions between items A, B, C, D}
Here's how to iterate over the elements in reverse order:
\snippet code/doc_src_qiterator.cpp 27multi
If you want to find all occurrences of a particular value, use
findNext() or findPrevious() in a loop. For example:
\snippet code/doc_src_qiterator.cpp 28multi
Multiple iterators can be used on the same map. If the map is
modified while a QMultiMapIterator is active, the QMultiMapIterator will
continue iterating over the original map, ignoring the modified
copy.
\sa QMutableMultiMapIterator
*/
/*!
\class QHashIterator
\inmodule QtCore
\ingroup java-style-iterators
\brief The QHashIterator class provides a Java-style const iterator for QHash and QMultiHash.
QHash has both \l{Java-style iterators} and \l{STL-style
iterators}. STL-style iterators are more efficient and should
be preferred. The template parameter \a Key specifies the hash's
key type, and \a T specifies the value type.
QHashIterator\<Key, T\> allows you to iterate over a QHash (or a
QMultiHash). If you want to modify the hash as you iterate over
it, use QMutableHashIterator instead.
The QHashIterator constructor takes a QHash as argument. After
construction, the iterator is located at the very beginning of
the hash (before the first item). Here's how to iterate over all
the elements sequentially:
\snippet code/doc_src_qiterator.cpp 29
The next() function returns the next item in the hash and
advances the iterator. The key() and value() functions return the
key and value of the last item that was jumped over.
Unlike STL-style iterators, Java-style iterators point \e between
items rather than directly \e at items. The first call to next()
advances the iterator to the position between the first and
second item, and returns the first item; the second call to
next() advances the iterator to the position between the second
and third item; and so on.
\image javaiterators1.svg {Iterator positions between items A, B, C, D}
If you want to find all occurrences of a particular value, use
findNext() in a loop. For example:
\snippet code/doc_src_qiterator.cpp 31
Multiple iterators can be used on the same hash. If the hash is
modified while a QHashIterator is active, the QHashIterator will
continue iterating over the original hash, ignoring the modified
copy.
\sa QMutableHashIterator, QHash::const_iterator
*/
/*!
\class QMutableMapIterator
\inmodule QtCore
\ingroup java-style-iterators
\brief The QMutableMapIterator class provides a Java-style non-const iterator for QMap.
QMap has both \l{Java-style iterators} and \l{STL-style
iterators}. STL-style iterators are more efficient and should
be preferred. The template parameter \a Key specifies the map's
key type, and \a T specifies the value type.
QMutableMapIterator\<Key, T\> allows you to iterate over a QMap
and modify the map. If you don't want to modify
the map (or have a const QMap), use the slightly faster
QMapIterator instead.
The QMutableMapIterator constructor takes a QMap as argument.
After construction, the iterator is located at the very beginning
of the map (before the first item). Here's how to iterate over
all the elements sequentially:
\snippet code/doc_src_qiterator.cpp 32
The next() function returns the next item in the map and
advances the iterator. The key() and value() functions return the
key and value of the last item that was jumped over.
Unlike STL-style iterators, Java-style iterators point \e between
items rather than directly \e at items. The first call to next()
advances the iterator to the position between the first and
second item, and returns the first item; the second call to
next() advances the iterator to the position between the second
and third item; and so on.
\image javaiterators1.svg {Iterator positions between items A, B, C, D}
Here's how to iterate over the elements in reverse order:
\snippet code/doc_src_qiterator.cpp 33
If you want to find all occurrences of a particular value, use
findNext() or findPrevious() in a loop. For example:
\snippet code/doc_src_qiterator.cpp 34
If you want to remove items as you iterate over the map, use
remove(). If you want to modify the value of an item, use
setValue().
Example:
\snippet code/doc_src_qiterator.cpp 35
The example removes all (key, value) pairs where the key and the
value are the same.
Only one mutable iterator can be active on a given map at any
time. Furthermore, no changes should be done directly to the map
while the iterator is active (as opposed to through the
iterator), since this could invalidate the iterator and lead to
undefined behavior.
\sa QMapIterator, QMap::iterator
*/
/*!
\class QMutableMultiMapIterator
\inmodule QtCore
\brief The QMutableMultiMapIterator class provides a Java-style non-const iterator for QMultiMap.
QMultiMap has both \l{Java-style iterators} and \l{STL-style
iterators}. STL-style iterators are more efficient and should
be preferred. The template parameter \a Key specifies the map's
key type, and \a T specifies the value type.
QMutableMultiMapIterator\<Key, T\> allows you to iterate over a QMultiMap
and modify the map. If you don't want to modify
the map (or have a const QMultiMap), use the slightly faster
QMultiMapIterator instead.
The QMutableMultiMapIterator constructor takes a QMultiMap as argument.
After construction, the iterator is located at the very beginning
of the map (before the first item). Here's how to iterate over
all the elements sequentially:
\snippet code/doc_src_qiterator.cpp 32multi
The next() function returns the next item in the map and
advances the iterator. The key() and value() functions return the
key and value of the last item that was jumped over.
Unlike STL-style iterators, Java-style iterators point \e between
items rather than directly \e at items. The first call to next()
advances the iterator to the position between the first and
second item, and returns the first item; the second call to
next() advances the iterator to the position between the second
and third item; and so on.
\image javaiterators1.svg {Iterator positions between items A, B, C, D}
Here's how to iterate over the elements in reverse order:
\snippet code/doc_src_qiterator.cpp 33multi
If you want to find all occurrences of a particular value, use
findNext() or findPrevious() in a loop. For example:
\snippet code/doc_src_qiterator.cpp 34multi
If you want to remove items as you iterate over the map, use
remove(). If you want to modify the value of an item, use
setValue().
Example:
\snippet code/doc_src_qiterator.cpp 35multi
The example removes all (key, value) pairs where the key and the
value are the same.
Only one mutable iterator can be active on a given map at any
time. Furthermore, no changes should be done directly to the map
while the iterator is active (as opposed to through the
iterator), since this could invalidate the iterator and lead to
undefined behavior.
\sa QMultiMapIterator, QMultiMap::iterator
*/
/*!
\class QMutableHashIterator
\inmodule QtCore
\ingroup java-style-iterators
\brief The QMutableHashIterator class provides a Java-style non-const iterator for QHash and QMultiHash.
QHash has both \l{Java-style iterators} and \l{STL-style
iterators}. STL-style iterators are more efficient and should
be preferred. The template parameter \a Key specifies the hash's
key type, and \a T specifies the value type.
QMutableHashIterator\<Key, T\> allows you to iterate over a QHash
and modify the hash. If you don't want to modify the hash (or have
a const QHash), use the slightly faster QHashIterator instead.
The QMutableHashIterator constructor takes a QHash as argument.
After construction, the iterator is located at the very beginning
of the hash (before the first item). Here's how to iterate over
all the elements sequentially:
\snippet code/doc_src_qiterator.cpp 36
The next() function returns the next item in the hash and
advances the iterator. The key() and value() functions return the
key and value of the last item that was jumped over.
Unlike STL-style iterators, Java-style iterators point \e between
items rather than directly \e at items. The first call to next()
advances the iterator to the position between the first and
second item, and returns the first item; the second call to
next() advances the iterator to the position between the second
and third item; and so on.
\image javaiterators1.svg {Iterator positions between items A, B, C, D}
If you want to find all occurrences of a particular value, use
findNext() in a loop. For example:
\snippet code/doc_src_qiterator.cpp 38
If you want to remove items as you iterate over the hash, use
remove(). If you want to modify the value of an item, use
setValue().
Example:
\snippet code/doc_src_qiterator.cpp 39
The example removes all (key, value) pairs where the key and the
value are the same.
Only one mutable iterator can be active on a given hash at any
time. Furthermore, no changes should be done directly to the hash
while the iterator is active (as opposed to through the
iterator), since this could invalidate the iterator and lead to
undefined behavior.
\sa QHashIterator, QHash::iterator
*/
/*! \fn template <class Key, class T> QMapIterator<Key, T>::QMapIterator(const QMap<Key, T> &map)
\fn template <class Key, class T> QMutableMapIterator<Key, T>::QMutableMapIterator(QMap<Key, T> &map)
\fn template <class Key, class T> QMultiMapIterator<Key, T>::QMultiMapIterator(const QMultiMap<Key, T> &map)
\fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::QMutableMultiMapIterator(QMultiMap<Key, T> &map)
Constructs an iterator for traversing \a map. The iterator is set
to be at the front of the map (before the first item).
\sa operator=()
*/
/*! \fn template <class Key, class T> QHashIterator<Key, T>::QHashIterator(const QHash<Key, T> &hash)
\fn template <class Key, class T> QMutableHashIterator<Key, T>::QMutableHashIterator(QHash<Key, T> &hash)
Constructs an iterator for traversing \a hash. The iterator is
set to be at the front of the hash (before the first item).
\sa operator=()
*/
/*! \fn template <class Key, class T> QMapIterator &QMapIterator<Key, T>::operator=(const QMap<Key, T> &map)
\fn template <class Key, class T> QMutableMapIterator &QMutableMapIterator<Key, T>::operator=(QMap<Key, T> &map)
\fn template <class Key, class T> QMultiMapIterator &QMultiMapIterator<Key, T>::operator=(const QMultiMap<Key, T> &map)
\fn template <class Key, class T> QMutableMultiMapIterator &QMutableMultiMapIterator<Key, T>::operator=(QMultiMap<Key, T> &map)
Makes the iterator operate on \a map. The iterator is set to be
at the front of the map (before the first item).
\sa toFront(), toBack()
*/
/*! \fn template <class Key, class T> QHashIterator &QHashIterator<Key, T>::operator=(const QHash<Key, T> &hash)
\fn template <class Key, class T> QMutableHashIterator &QMutableHashIterator<Key, T>::operator=(QHash<Key, T> &hash)
Makes the iterator operate on \a hash. The iterator is set to be
at the front of the hash (before the first item).
\sa toFront(), toBack()
*/
/*! \fn template <class Key, class T> void QMapIterator<Key, T>::toFront()
\fn template <class Key, class T> void QMultiMapIterator<Key, T>::toFront()
\fn template <class Key, class T> void QHashIterator<Key, T>::toFront()
\fn template <class Key, class T> void QMutableMapIterator<Key, T>::toFront()
\fn template <class Key, class T> void QMutableMultiMapIterator<Key, T>::toFront()
\fn template <class Key, class T> void QMutableHashIterator<Key, T>::toFront()
Moves the iterator to the front of the container (before the
first item).
\sa toBack(), next()
*/
/*! \fn template <class Key, class T> void QMapIterator<Key, T>::toBack()
\fn template <class Key, class T> void QMultiMapIterator<Key, T>::toBack()
\fn template <class Key, class T> void QMutableMapIterator<Key, T>::toBack()
\fn template <class Key, class T> void QMutableMultiMapIterator<Key, T>::toBack()
Moves the iterator to the back of the container (after the last
item).
\sa toFront(), previous()
*/
/*!
\fn template <class Key, class T> void QHashIterator<Key, T>::toBack()
\fn template <class Key, class T> void QMutableHashIterator<Key, T>::toBack()
Moves the iterator to the back of the container (after the last
item).
\sa toFront()
*/
/*! \fn template <class Key, class T> bool QMapIterator<Key, T>::hasNext() const
\fn template <class Key, class T> bool QMultiMapIterator<Key, T>::hasNext() const
\fn template <class Key, class T> bool QMutableMapIterator<Key, T>::hasNext() const
\fn template <class Key, class T> bool QMutableMultiMapIterator<Key, T>::hasNext() const
Returns \c true if there is at least one item ahead of the iterator,
i.e. the iterator is \e not at the back of the container;
otherwise returns \c false.
\sa hasPrevious(), next()
*/
/*!
\fn template <class Key, class T> bool QHashIterator<Key, T>::hasNext() const
\fn template <class Key, class T> bool QMutableHashIterator<Key, T>::hasNext() const
Returns \c true if there is at least one item ahead of the iterator,
i.e. the iterator is \e not at the back of the container;
otherwise returns \c false.
\sa next()
*/
/*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::next()
\fn template <class Key, class T> QMultiMapIterator<Key, T>::Item QMultiMapIterator<Key, T>::next()
Returns the next item and advances the iterator by one position.
Call key() on the return value to obtain the item's key, and
value() to obtain the value.
Calling this function on an iterator located at the back of the
container leads to undefined results.
\sa hasNext(), {QMapIterator::}{peekNext()}, previous()
*/
/*! \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::next()
\fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::next()
Returns the next item and advances the iterator by one position.
Call key() on the return value to obtain the item's key, and
value() to obtain the value.
Calling this function on an iterator located at the back of the
container leads to undefined results.
\sa hasNext(), peekNext(), previous()
*/
/*!
\fn template <class Key, class T> QHashIterator<Key, T>::Item QHashIterator<Key, T>::next()
Returns the next item and advances the iterator by one position.
Call key() on the return value to obtain the item's key, and
value() to obtain the value.
Calling this function on an iterator located at the back of the
container leads to undefined results.
\sa hasNext(), peekNext()
*/
/*!
\fn template <class Key, class T> QMutableHashIterator<Key, T>::Item QMutableHashIterator<Key, T>::next()
Returns the next item and advances the iterator by one position.
Call key() on the return value to obtain the item's key, and
value() to obtain the value.
Calling this function on an iterator located at the back of the
container leads to undefined results.
\sa hasNext(), peekNext()
*/
/*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::peekNext() const
\fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekNext() const
Returns the next item without moving the iterator.
Call key() on the return value to obtain the item's key, and
value() to obtain the value.
Calling this function on an iterator located at the back of the
container leads to undefined results.
\sa hasNext(), next(), peekPrevious()
*/
/*!
\fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::peekNext() const
Returns a reference to the next item without moving the iterator.
Call key() on the return value to obtain the item's key, and
value() to obtain the value.
Calling this function on an iterator located at the back of the
container leads to undefined results.
\sa hasNext(), next(), peekPrevious()
*/
/*!
\fn template <class Key, class T> QHashIterator<Key, T>::Item QHashIterator<Key, T>::peekNext() const
Returns the next item without moving the iterator.
Call key() on the return value to obtain the item's key, and
value() to obtain the value.
Calling this function on an iterator located at the back of the
container leads to undefined results.
\sa hasNext(), next()
*/
/*!
\fn template <class Key, class T> QMutableHashIterator<Key, T>::Item QMutableHashIterator<Key, T>::peekNext() const
Returns a reference to the next item without moving the iterator.
Call key() on the return value to obtain the item's key, and
value() to obtain the value.
Calling this function on an iterator located at the back of the
container leads to undefined results.
\sa hasNext(), next()
*/
/*! \fn template <class Key, class T> bool QMapIterator<Key, T>::hasPrevious() const
\fn template <class Key, class T> bool QMultiMapIterator<Key, T>::hasPrevious() const
\fn template <class Key, class T> bool QMutableMapIterator<Key, T>::hasPrevious() const
\fn template <class Key, class T> bool QMutableMultiMapIterator<Key, T>::hasPrevious() const
Returns \c true if there is at least one item behind the iterator,
i.e. the iterator is \e not at the front of the container;
otherwise returns \c false.
\sa hasNext(), previous()
*/
/*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::previous()
\fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::previous()
\fn template <class Key, class T> QMultiMapIterator<Key, T>::Item QMultiMapIterator<Key, T>::previous()
\fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::previous()
Returns the previous item and moves the iterator back by one
position.
Call key() on the return value to obtain the item's key, and
value() to obtain the value.
Calling this function on an iterator located at the front of the
container leads to undefined results.
\sa hasPrevious(), peekPrevious(), next()
*/
/*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::peekPrevious() const
\fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekPrevious() const
\fn template <class Key, class T> QMultiMapIterator<Key, T>::Item QMultiMapIterator<Key, T>::peekPrevious() const
\fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::peekPrevious() const
Returns the previous item without moving the iterator.
Call key() on the return value to obtain the item's key, and
value() to obtain the value.
Calling this function on an iterator located at the front of the
container leads to undefined results.
\sa hasPrevious(), previous(), {QMapIterator::}{peekNext()}
*/
/*! \fn template <class Key, class T> const T &QMapIterator<Key, T>::value() const
\fn template <class Key, class T> const T &QMultiMapIterator<Key, T>::value() const
Returns the value of the last item that was jumped over using one
of the traversal functions (next(), previous(), findNext(),
findPrevious()).
After a call to next() or findNext(), value() is
equivalent to peekPrevious().value(). After a call to previous()
or findPrevious(), value() is equivalent to peekNext().value().
\sa key()
*/
/*!
\fn template <class Key, class T> const T &QMutableMapIterator<Key, T>::value() const
\fn template <class Key, class T> const T &QMutableMultiMapIterator<Key, T>::value() const
Returns the value of the last item that was jumped over using one
of the traversal functions (next(), previous(), findNext(),
findPrevious()).
After a call to next() or findNext(), value() is
equivalent to peekPrevious().value(). After a call to previous()
or findPrevious(), value() is equivalent to peekNext().value().
\sa key(), setValue()
*/
/*! \fn template <class Key, class T> const T &QHashIterator<Key, T>::value() const
Returns the value of the last item that was jumped over using one
of the traversal functions (next(), findNext()).
\sa key()
*/
/*!
\fn template <class Key, class T> const T &QMutableHashIterator<Key, T>::value() const
Returns the value of the last item that was jumped over using one
of the traversal functions (next(), findNext()).
\sa key(), setValue()
*/
/*!
\fn template <class Key, class T> T &QMutableMapIterator<Key, T>::value()
\fn template <class Key, class T> T &QMutableMultiMapIterator<Key, T>::value()
\fn template <class Key, class T> T &QMutableHashIterator<Key, T>::value()
\overload
Returns a non-const reference to the value of
the last item that was jumped over using one
of the traversal functions.
*/
/*! \fn template <class Key, class T> const Key &QMapIterator<Key, T>::key() const
\fn template <class Key, class T> const Key &QMutableMapIterator<Key, T>::key() const
\fn template <class Key, class T> const Key &QMultiMapIterator<Key, T>::key() const
\fn template <class Key, class T> const Key &QMutableMultiMapIterator<Key, T>::key() const
Returns the key of the last item that was jumped over using one
of the traversal functions (next(), previous(), findNext(),
findPrevious()).
After a call to next() or findNext(), key() is
equivalent to peekPrevious().key(). After a call to previous() or
findPrevious(), key() is equivalent to peekNext().key().
\sa value()
*/
/*! \fn template <class Key, class T> const Key &QHashIterator<Key, T>::key() const
\fn template <class Key, class T> const Key &QMutableHashIterator<Key, T>::key() const
Returns the key of the last item that was jumped over using one
of the traversal functions (next(), findNext()).
\sa value()
*/
/*! \fn template <class Key, class T> bool QMapIterator<Key, T>::findNext(const T &value)
\fn template <class Key, class T> bool QMutableMapIterator<Key, T>::findNext(const T &value)
\fn template <class Key, class T> bool QMultiMapIterator<Key, T>::findNext(const T &value)
\fn template <class Key, class T> bool QMutableMultiMapIterator<Key, T>::findNext(const T &value)
Searches for \a value starting from the current iterator position
forward. Returns \c true if a (key, value) pair with value \a value
is found; otherwise returns \c false.
After the call, if \a value was found, the iterator is positioned
just after the matching item; otherwise, the iterator is
positioned at the back of the container.
\sa findPrevious()
*/
/*! \fn template <class Key, class T> bool QHashIterator<Key, T>::findNext(const T &value)
\fn template <class Key, class T> bool QMutableHashIterator<Key, T>::findNext(const T &value)
Searches for \a value starting from the current iterator position
forward. Returns \c true if a (key, value) pair with value \a value
is found; otherwise returns \c false.
After the call, if \a value was found, the iterator is positioned
just after the matching item; otherwise, the iterator is
positioned at the back of the container.
*/
/*! \fn template <class Key, class T> bool QMapIterator<Key, T>::findPrevious(const T &value)
\fn template <class Key, class T> bool QMutableMapIterator<Key, T>::findPrevious(const T &value)
\fn template <class Key, class T> bool QMultiMapIterator<Key, T>::findPrevious(const T &value)
\fn template <class Key, class T> bool QMutableMultiMapIterator<Key, T>::findPrevious(const T &value)
Searches for \a value starting from the current iterator position
backward. Returns \c true if a (key, value) pair with value \a value
is found; otherwise returns \c false.
After the call, if \a value was found, the iterator is positioned
just before the matching item; otherwise, the iterator is
positioned at the front of the container.
\sa findNext()
*/
/*! \fn template <class Key, class T> void QMutableMapIterator<Key, T>::remove()
\fn template <class Key, class T> void QMutableMultiMapIterator<Key, T>::remove()
Removes the last item that was jumped over using one of the
traversal functions (next(), previous(), findNext(), findPrevious()).
\sa setValue()
*/
/*! \fn template <class Key, class T> void QMutableHashIterator<Key, T>::remove()
Removes the last item that was jumped over using one of the
traversal functions (next(), findNext()).
\sa setValue()
*/
/*! \fn template <class Key, class T> void QMutableMapIterator<Key, T>::setValue(const T &value)
\fn template <class Key, class T> void QMutableMultiMapIterator<Key, T>::setValue(const T &value)
Replaces the value of the last item that was jumped over using
one of the traversal functions with \a value.
The traversal functions are next(), previous(), findNext(), and
findPrevious().
\sa key(), value(), remove()
*/
/*!
\fn template <class Key, class T> void QMutableHashIterator<Key, T>::setValue(const T &value)
Replaces the value of the last item that was jumped over using
one of the traversal functions with \a value.
The traversal functions are next() and findNext().
\sa key(), value(), remove()
*/