1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
4/*! \class QKeyValueIterator
8 \brief Iterator over the key/value pairs of an associative container.
10 The QKeyValueIterator class provides an STL-style iterator for returning
11 key/value pairs from associative containers like QHash and QMap. It
12 supports the same API as the STL associative containers, i.e. getting a
13 key/value pair when iterating through the container.
15 This will allow for better interoperability between QMap, QHash and friends
16 and STL-style algorithms.
18 \warning Iterators on implicitly shared containers do not work
19 exactly like STL-iterators. You should avoid copying a container
20 while iterators are active on that container. For more information,
21 read \l{Implicit sharing iterator problem}.
24/*! \typedef QKeyValueIterator::iterator_category
28/*! \typedef QKeyValueIterator::difference_type
32/*! \typedef QKeyValueIterator::value_type
36/*! \struct QKeyValueIterator::pointer
40/*! \typedef QKeyValueIterator::reference
44/*! \fn template<typename Key, typename T, class Iterator> QKeyValueIterator<Key, T, Iterator>::QKeyValueIterator()
46 Constructs a default QKeyValueIterator.
49/*! \fn template<typename Key, typename T, class Iterator> QKeyValueIterator<Key, T, Iterator>::QKeyValueIterator(Iterator o)
51 Constructs a QKeyValueIterator on top of \a o.
54/*! \fn template<typename Key, typename T, class Iterator> std::pair<Key, T> QKeyValueIterator<Key, T, Iterator>::operator*() const
56 Returns the current entry as a pair.
59/*! \fn template<typename Key, typename T, class Iterator> pointer QKeyValueIterator<Key, T, Iterator>::operator->() const
61 Returns the current entry as a pointer-like object to the pair.
68/*! \fn template<typename Key, typename T, class Iterator> bool QKeyValueIterator<Key, T, Iterator>::operator==(QKeyValueIterator<Key, T, Iterator> lhs, QKeyValueIterator<Key, T, Iterator> rhs)
70 Returns \c true if \a rhs points to the same item as \a lhs otherwise returns
76/*! \fn template<typename Key, typename T, class Iterator> bool QKeyValueIterator<Key, T, Iterator>::operator!=(QKeyValueIterator<Key, T, Iterator> lhs, QKeyValueIterator<Key, T, Iterator> rhs)
78 Returns \c true if \a rhs points to a different item than \a lhs otherwise
85 \fn template<typename Key, typename T, class Iterator> QKeyValueIterator &QKeyValueIterator<Key, T, Iterator>::operator++()
87 The prefix \c{++} operator (\c{++i}) advances the iterator to the
88 next item in the container and returns the iterator.
90 \note Advancing the iterator past its container's end() constitutes
96/*! \fn template<typename Key, typename T, class Iterator> QKeyValueIterator QKeyValueIterator<Key, T, Iterator>::operator++(int)
100 The postfix \c{++} operator (\c{i++}) advances the iterator to the
101 next item in the container and returns the iterator's prior value.
103 \note Advancing the iterator past its container's end() constitutes
107/*! \fn template<typename Key, typename T, class Iterator> QKeyValueIterator &QKeyValueIterator<Key, T, Iterator>::operator--()
109 The prefix c{--} operator (\c{--i}) backs the iterator up to the previous item
110 in the container and returns the iterator.
112 \note Backing up an iterator to before its container's begin() constitutes
118/*! \fn template<typename Key, typename T, class Iterator> QKeyValueIterator QKeyValueIterator<Key, T, Iterator>::operator--(int)
122 The postfix c{--} operator (\c{i--}) backs the iterator up to the previous item
123 in the container and returns the iterator's prior value.
125 \note Backing up an iterator to before its container's begin() constitutes
129/*! \fn template<typename Key, typename T, class Iterator> Iterator QKeyValueIterator<Key, T, Iterator>::base() const
130 Returns the underlying iterator this QKeyValueIterator is based on.
137 \brief The QListIterator class provides a Java-style const iterator for QList and QQueue.
139 QList has both \l{Java-style iterators} and \l{STL-style
140 iterators}. STL-style iterators are more efficient and should
143 An alternative to using iterators is to use index positions. Most
144 QList member functions take an index as their first parameter,
145 making it possible to access, modify, and remove items without
148 QListIterator<T> allows you to iterate over a QList<T>,
149 a QQueue<T> or a QStack<T>. If you want to modify the list
150 as you iterate over it, use QMutableListIterator<T> instead.
152 The QListIterator constructor takes a QList as argument. After
153 construction, the iterator is located at the very beginning of
154 the list (before the first item). Here's how to iterate over all
155 the elements sequentially:
157 \snippet code/doc_src_qiterator.cpp 0
159 The next() function returns the next item in the list and
160 advances the iterator. Unlike STL-style iterators, Java-style
161 iterators point \e between items rather than directly \e at
162 items. The first call to next() advances the iterator to the
163 position between the first and second item, and returns the first
164 item; the second call to next() advances the iterator to the
165 position between the second and third item, and returns the second
168 \image javaiterators1.png
170 Here's how to iterate over the elements in reverse order:
172 \snippet code/doc_src_qiterator.cpp 1
174 If you want to find all occurrences of a particular value, use
175 findNext() or findPrevious() in a loop.
177 Multiple iterators can be used on the same list. If the list is
178 modified while a QListIterator is active, the QListIterator will
179 continue iterating over the original list, ignoring the modified
182 \sa QMutableListIterator, QList::const_iterator
188 \brief The QSetIterator class provides a Java-style const iterator for QSet.
190 QSet has both \l{Java-style iterators} and \l{STL-style
191 iterators}. STL-style iterators are more efficient and should
194 QSetIterator<T> allows you to iterate over a QSet<T>. If you
195 want to modify the set as you iterate over it, use
196 QMutableSetIterator<T> instead.
198 The constructor takes a QSet as argument. After construction, the
199 iterator is located at the very beginning of the set (before
200 the first item). Here's how to iterate over all the elements
203 \snippet code/doc_src_qiterator.cpp 6
205 The next() function returns the next item in the set and
206 advances the iterator. Unlike STL-style iterators, Java-style
207 iterators point \e between items rather than directly \e at
208 items. The first call to next() advances the iterator to the
209 position between the first and second item, and returns the first
210 item; the second call to next() advances the iterator to the
211 position between the second and third item, returning the second
214 \image javaiterators1.png
216 If you want to find all occurrences of a particular value, use
217 findNext() in a loop.
219 Multiple iterators can be used on the same set. If the set
220 is modified while a QSetIterator is active, the QSetIterator
221 will continue iterating over the original set, ignoring the
224 \sa QMutableSetIterator, QSet::const_iterator
228 \class QMutableListIterator
231 \brief The QMutableListIterator class provides a Java-style non-const iterator for QList, QQueue and QStack.
233 QList has both \l{Java-style iterators} and \l{STL-style
234 iterators}. STL-style iterators are more efficient and should
237 An alternative to using iterators is to use index positions. Most
238 QList member functions take an index as their first parameter,
239 making it possible to access, insert, and remove items without
242 QMutableListIterator<T> allows you to iterate over a QList<T>
243 (or a QQueue<T>) and modify the list. If you don't want to
244 modify the list (or have a const QList), use the slightly faster
245 QListIterator<T> instead.
247 The QMutableListIterator constructor takes a QList as argument.
248 After construction, the iterator is located at the very beginning
249 of the list (before the first item). Here's how to iterate over
250 all the elements sequentially:
252 \snippet code/doc_src_qiterator.cpp 8
254 The next() function returns the next item in the list and
255 advances the iterator. Unlike STL-style iterators, Java-style
256 iterators point \e between items rather than directly \e at
257 items. The first call to next() advances the iterator to the
258 position between the first and second item, and returns the first
259 item; the second call to next() advances the iterator to the
260 position between the second and third item, returning the second
263 \image javaiterators1.png
265 Here's how to iterate over the elements in reverse order:
267 \snippet code/doc_src_qiterator.cpp 9
269 If you want to find all occurrences of a particular value, use
270 findNext() or findPrevious() in a loop.
272 If you want to remove items as you iterate over the list, use
273 remove(). If you want to modify the value of an item, use
274 setValue(). If you want to insert a new item in the list, use
278 \snippet code/doc_src_qiterator.cpp 10
280 The example traverses a list, replacing negative numbers with
281 their absolute values, and eliminating zeroes.
283 Only one mutable iterator can be active on a given list at any
284 time. Furthermore, no changes should be done directly to the list
285 while the iterator is active (as opposed to through the
286 iterator), since this could invalidate the iterator and lead to
289 \sa QListIterator, QList::iterator
293 \class QMutableSetIterator
297 \brief The QMutableSetIterator class provides a Java-style non-const iterator for QSet.
299 QSet has both \l{Java-style iterators} and \l{STL-style
300 iterators}. STL-style iterators are more efficient and should
303 QMutableSetIterator<T> allows you to iterate over a QSet<T>
304 and remove items from the set as you iterate. If you don't want
305 to modify the set (or have a const QSet), use the slightly faster
306 QSetIterator<T> instead.
308 The QMutableSetIterator constructor takes a QSet as argument.
309 After construction, the iterator is located at the very beginning
310 of the set (before the first item). Here's how to iterate over
311 all the elements sequentially:
313 \snippet code/doc_src_qiterator.cpp 17
315 The next() function returns the next item in the set and
316 advances the iterator. Unlike STL-style iterators, Java-style
317 iterators point \e between items rather than directly \e at
318 items. The first call to next() advances the iterator to the
319 position between the first and second item, and returns the first
320 item; the second call to next() advances the iterator to the
321 position between the second and third item, returning the second
324 \image javaiterators1.png
326 If you want to remove items as you iterate over the set, use
329 Only one mutable iterator can be active on a given set at any
330 time. Furthermore, no changes should be done directly to the set
331 while the iterator is active (as opposed to through the
332 iterator), since this could invalidate the iterator and lead to
335 \sa QSetIterator, QSet::iterator
339 \fn template <class T> QListIterator<T>::QListIterator(const QList<T> &list)
340 \fn template <class T> QMutableListIterator<T>::QMutableListIterator(QList<T> &list)
342 Constructs an iterator for traversing \a list. The iterator is
343 set to be at the front of the list (before the first item).
349 \fn template <class T> QSetIterator<T>::QSetIterator(const QSet<T> &set)
350 \fn template <class T> QMutableSetIterator<T>::QMutableSetIterator(QSet<T> &set)
352 Constructs an iterator for traversing \a set. The iterator is
353 set to be at the front of the set (before the first item).
358/*! \fn template <class T> QMutableListIterator &QMutableListIterator<T>::operator=(QList<T> &list)
359 \fn template <class T> QListIterator &QListIterator<T>::operator=(const QList<T> &list)
361 Makes the iterator operate on \a list. The iterator is set to be
362 at the front of the list (before the first item).
364 \sa toFront(), toBack()
367/*! \fn template <class T> QSetIterator &QSetIterator<T>::operator=(const QSet<T> &set)
368 \fn template <class T> QMutableSetIterator &QMutableSetIterator<T>::operator=(QSet<T> &set)
370 Makes the iterator operate on \a set. The iterator is set to be
371 at the front of the set (before the first item).
373 \sa toFront(), toBack()
376/*! \fn template <class T> void QListIterator<T>::toFront()
377 \fn template <class T> void QSetIterator<T>::toFront()
378 \fn template <class T> void QMutableListIterator<T>::toFront()
379 \fn template <class T> void QMutableSetIterator<T>::toFront()
381 Moves the iterator to the front of the container (before the
387/*! \fn template <class T> void QListIterator<T>::toBack()
388 \fn template <class T> void QMutableListIterator<T>::toBack()
391 Moves the iterator to the back of the container (after the last
395 \sa toFront(), previous()
398/*! \fn template <class T> void QSetIterator<T>::toBack()
399 \include qiterator.qdoc toBack
403/*! \fn template <class T> void QMutableSetIterator<T>::toBack()
405 Moves the iterator to the back of the container (after the last
411/*! \fn template <class T> bool QListIterator<T>::hasNext() const
412 \fn template <class T> bool QMutableListIterator<T>::hasNext() const
415 Returns \c true if there is at least one item ahead of the iterator,
416 i.e. the iterator is \e not at the back of the container;
417 otherwise returns \c false.
420 \sa hasPrevious(), next()
423/*! \fn template <class T> bool QSetIterator<T>::hasNext() const
424 \include qiterator.qdoc hasNext
428/*! \fn template <class T> bool QMutableSetIterator<T>::hasNext() const
430 Returns \c true if there is at least one item ahead of the iterator,
431 i.e. the iterator is \e not at the back of the container;
432 otherwise returns \c false.
437/*! \fn template <class T> const T &QListIterator<T>::next()
440 Returns the next item and advances the iterator by one position.
442 Calling this function on an iterator located at the back of the
443 container leads to undefined results.
446 \sa hasNext(), peekNext(), previous()
450 \fn template <class T> const T &QSetIterator<T>::next()
451 \include qiterator.qdoc next
452 \sa hasNext(), peekNext()
455/* \fn template <class T> const T &QMutableSetIterator<T>::next()
456 Returns the next item and advances the iterator by one position.
458 Calling this function on an iterator located at the back of the
459 container leads to undefined results.
461 \sa hasNext(), peekNext()
464/*! \fn template <class T> const T &QMutableSetIterator<T>::next()
466 Returns the next item and advances the iterator by one position.
468 Calling this function on an iterator located at the back of the
469 container leads to undefined results.
471 \sa hasNext(), peekNext()
474/*! \fn template <class T> T &QMutableListIterator<T>::next()
476 Returns a reference to the next item, and advances the iterator
479 Calling this function on an iterator located at the back of the
480 container leads to undefined results.
482 \sa hasNext(), peekNext(), previous()
485/*! \fn template <class T> const T &QListIterator<T>::peekNext() const
488 Returns the next item without moving the iterator.
490 Calling this function on an iterator located at the back of the
491 container leads to undefined results.
494 \sa hasNext(), next(), peekPrevious()
498 \fn template <class T> const T &QSetIterator<T>::peekNext() const
499 \include qiterator.qdoc peekNext
500 \sa hasNext(), next()
504 \fn template <class T> const T &QMutableSetIterator<T>::peekNext() const
506 Returns the next item without moving the iterator.
508 Calling this function on an iterator located at the back of the
509 container leads to undefined results.
511 \sa hasNext(), next()
514/*! \fn template <class T> T &QMutableListIterator<T>::peekNext() const
516 Returns a reference to the next item, without moving the iterator.
518 Calling this function on an iterator located at the back of the
519 container leads to undefined results.
521 \sa hasNext(), next(), peekPrevious()
524/*! \fn template <class T> bool QListIterator<T>::hasPrevious() const
525 \fn template <class T> bool QMutableListIterator<T>::hasPrevious() const
527 Returns \c true if there is at least one item behind the iterator,
528 i.e. the iterator is \e not at the front of the container;
529 otherwise returns \c false.
531 \sa hasNext(), previous()
534/*! \fn template <class T> const T &QListIterator<T>::previous()
536 Returns the previous item and moves the iterator back by one
539 Calling this function on an iterator located at the front of the
540 container leads to undefined results.
542 \sa hasPrevious(), peekPrevious(), next()
545/*! \fn template <class T> T &QMutableListIterator<T>::previous()
547 Returns a reference to the previous item and moves the iterator
548 back by one position.
550 Calling this function on an iterator located at the front of the
551 container leads to undefined results.
553 \sa hasPrevious(), peekPrevious(), next()
556/*! \fn template <class T> const T &QListIterator<T>::peekPrevious() const
558 Returns the previous item without moving the iterator.
560 Calling this function on an iterator located at the front of the
561 container leads to undefined results.
563 \sa hasPrevious(), previous(), peekNext()
566/*! \fn template <class T> T &QMutableListIterator<T>::peekPrevious() const
568 Returns a reference to the previous item, without moving the iterator.
570 Calling this function on an iterator located at the front of the
571 container leads to undefined results.
573 \sa hasPrevious(), previous(), peekNext()
577 \fn template <class T> bool QMutableSetIterator<T>::findNext(const T &value)
579 Searches for \a value starting from the current iterator position
580 forward. Returns \c true if \a value is found; otherwise returns \c false.
582 After the call, if \a value was found, the iterator is positioned
583 just after the matching item; otherwise, the iterator is
584 positioned at the back of the container.
587/*! \fn template <class T> bool QListIterator<T>::findNext(const T &value)
588 \fn template <class T> bool QMutableListIterator<T>::findNext(const T &value)
591 Searches for \a value starting from the current iterator position
592 forward. Returns \c true if \a value is found; otherwise returns \c false.
594 After the call, if \a value was found, the iterator is positioned
595 just after the matching item; otherwise, the iterator is
596 positioned at the back of the container.
602/*! \fn template <class T> bool QSetIterator<T>::findNext(const T &value)
603 \include qiterator.qdoc findNext
606/*! \fn template <class T> bool QListIterator<T>::findPrevious(const T &value)
607 \fn template <class T> bool QMutableListIterator<T>::findPrevious(const T &value)
609 Searches for \a value starting from the current iterator position
610 backward. Returns \c true if \a value is found; otherwise returns
613 After the call, if \a value was found, the iterator is positioned
614 just before the matching item; otherwise, the iterator is
615 positioned at the front of the container.
620/*! \fn template <class T> void QMutableListIterator<T>::remove()
622 Removes the last item that was jumped over using one of the
623 traversal functions (next(), previous(), findNext(), findPrevious()).
626 \snippet code/doc_src_qiterator.cpp 19
628 \sa insert(), setValue()
631/*! \fn template <class T> void QMutableSetIterator<T>::remove()
633 Removes the last item that was jumped over using one of the
634 traversal functions (next(), findNext()).
637 \snippet code/doc_src_qiterator.cpp 22
642/*! \fn template <class T> void QMutableListIterator<T>::setValue(const T &value) const
644 Replaces the value of the last item that was jumped over using
645 one of the traversal functions with \a value.
647 The traversal functions are next(), previous(), findNext(), and
651 \snippet code/doc_src_qiterator.cpp 23
653 \sa value(), remove(), insert()
656/*! \fn template <class T> const T &QMutableListIterator<T>::value() const
658 Returns the value of the last item that was jumped over using one
659 of the traversal functions (next(), previous(), findNext(),
662 After a call to next() or findNext(), value() is equivalent to
663 peekPrevious(). After a call to previous() or findPrevious(), value() is
664 equivalent to peekNext().
667/*! \fn template <class T> const T &QMutableSetIterator<T>::value() const
669 Returns the value of the last item that was jumped over using
670 next() or findNext().
674 \fn template <class T> T &QMutableListIterator<T>::value()
677 Returns a non-const reference to the value of the last item that
678 was jumped over using one of the traversal functions.
681/*! \fn template <class T> void QMutableListIterator<T>::insert(const T &value)
683 Inserts \a value at the current iterator position. After the
684 call, the iterator is located just after the inserted item.
686 \sa remove(), setValue()
693 \brief The QMapIterator class provides a Java-style const iterator for QMap.
695 QMap has both \l{Java-style iterators} and \l{STL-style
696 iterators}. STL-style iterators are more efficient and should
699 QMapIterator<Key, T> allows you to iterate over a QMap.
700 If you want to modify the map as you iterate over
701 it, use QMutableMapIterator instead.
703 The QMapIterator constructor takes a QMap as argument. After
704 construction, the iterator is located at the very beginning of
705 the map (before the first item). Here's how to iterate over all
706 the elements sequentially:
708 \snippet code/doc_src_qiterator.cpp 26
710 The next() function returns the next item in the map and
711 advances the iterator. The key() and value() functions return the
712 key and value of the last item that was jumped over.
714 Unlike STL-style iterators, Java-style iterators point \e between
715 items rather than directly \e at items. The first call to next()
716 advances the iterator to the position between the first and
717 second item, and returns the first item; the second call to
718 next() advances the iterator to the position between the second
719 and third item; and so on.
721 \image javaiterators1.png
723 Here's how to iterate over the elements in reverse order:
725 \snippet code/doc_src_qiterator.cpp 27
727 If you want to find all occurrences of a particular value, use
728 findNext() or findPrevious() in a loop. For example:
730 \snippet code/doc_src_qiterator.cpp 28
732 Multiple iterators can be used on the same map. If the map is
733 modified while a QMapIterator is active, the QMapIterator will
734 continue iterating over the original map, ignoring the modified
737 \sa QMutableMapIterator, QMap::const_iterator
741 \class QMultiMapIterator
744 \brief The QMultiMapIterator class provides a Java-style const iterator for QMultiMap.
745 QMultiMap has both \l{Java-style iterators} and \l{STL-style
746 iterators}. STL-style iterators are more efficient and should
749 QMultiMapIterator<Key, T> allows you to iterate over a QMultiMap.
750 If you want to modify the map as you iterate over
751 it, use QMutableMultiMapIterator instead.
753 The QMultiMapIterator constructor takes a QMultiMap as argument. After
754 construction, the iterator is located at the very beginning of
755 the map (before the first item). Here's how to iterate over all
756 the elements sequentially:
758 \snippet code/doc_src_qiterator.cpp 26multi
760 The next() function returns the next item in the map and
761 advances the iterator. The key() and value() functions return the
762 key and value of the last item that was jumped over.
764 Unlike STL-style iterators, Java-style iterators point \e between
765 items rather than directly \e at items. The first call to next()
766 advances the iterator to the position between the first and
767 second item, and returns the first item; the second call to
768 next() advances the iterator to the position between the second
769 and third item; and so on.
771 \image javaiterators1.png
773 Here's how to iterate over the elements in reverse order:
775 \snippet code/doc_src_qiterator.cpp 27multi
777 If you want to find all occurrences of a particular value, use
778 findNext() or findPrevious() in a loop. For example:
780 \snippet code/doc_src_qiterator.cpp 28multi
782 Multiple iterators can be used on the same map. If the map is
783 modified while a QMultiMapIterator is active, the QMultiMapIterator will
784 continue iterating over the original map, ignoring the modified
787 \sa QMutableMultiMapIterator
794 \brief The QHashIterator class provides a Java-style const iterator for QHash and QMultiHash.
796 QHash has both \l{Java-style iterators} and \l{STL-style
797 iterators}. STL-style iterators are more efficient and should
800 QHashIterator<Key, T> allows you to iterate over a QHash (or a
801 QMultiHash). If you want to modify the hash as you iterate over
802 it, use QMutableHashIterator instead.
804 The QHashIterator constructor takes a QHash as argument. After
805 construction, the iterator is located at the very beginning of
806 the hash (before the first item). Here's how to iterate over all
807 the elements sequentially:
809 \snippet code/doc_src_qiterator.cpp 29
811 The next() function returns the next item in the hash and
812 advances the iterator. The key() and value() functions return the
813 key and value of the last item that was jumped over.
815 Unlike STL-style iterators, Java-style iterators point \e between
816 items rather than directly \e at items. The first call to next()
817 advances the iterator to the position between the first and
818 second item, and returns the first item; the second call to
819 next() advances the iterator to the position between the second
820 and third item; and so on.
822 \image javaiterators1.png
824 If you want to find all occurrences of a particular value, use
825 findNext() in a loop. For example:
827 \snippet code/doc_src_qiterator.cpp 31
829 Multiple iterators can be used on the same hash. If the hash is
830 modified while a QHashIterator is active, the QHashIterator will
831 continue iterating over the original hash, ignoring the modified
834 \sa QMutableHashIterator, QHash::const_iterator
838 \class QMutableMapIterator
841 \brief The QMutableMapIterator class provides a Java-style non-const iterator for QMap.
843 QMap has both \l{Java-style iterators} and \l{STL-style
844 iterators}. STL-style iterators are more efficient and should
847 QMutableMapIterator<Key, T> allows you to iterate over a QMap
848 and modify the map. If you don't want to modify
849 the map (or have a const QMap), use the slightly faster
850 QMapIterator instead.
852 The QMutableMapIterator constructor takes a QMap as argument.
853 After construction, the iterator is located at the very beginning
854 of the map (before the first item). Here's how to iterate over
855 all the elements sequentially:
857 \snippet code/doc_src_qiterator.cpp 32
859 The next() function returns the next item in the map and
860 advances the iterator. The key() and value() functions return the
861 key and value of the last item that was jumped over.
863 Unlike STL-style iterators, Java-style iterators point \e between
864 items rather than directly \e at items. The first call to next()
865 advances the iterator to the position between the first and
866 second item, and returns the first item; the second call to
867 next() advances the iterator to the position between the second
868 and third item; and so on.
870 \image javaiterators1.png
872 Here's how to iterate over the elements in reverse order:
874 \snippet code/doc_src_qiterator.cpp 33
876 If you want to find all occurrences of a particular value, use
877 findNext() or findPrevious() in a loop. For example:
879 \snippet code/doc_src_qiterator.cpp 34
881 If you want to remove items as you iterate over the map, use
882 remove(). If you want to modify the value of an item, use
887 \snippet code/doc_src_qiterator.cpp 35
889 The example removes all (key, value) pairs where the key and the
892 Only one mutable iterator can be active on a given map at any
893 time. Furthermore, no changes should be done directly to the map
894 while the iterator is active (as opposed to through the
895 iterator), since this could invalidate the iterator and lead to
898 \sa QMapIterator, QMap::iterator
902 \class QMutableMultiMapIterator
905 \brief The QMutableMultiMapIterator class provides a Java-style non-const iterator for QMultiMap.
907 QMultiMap has both \l{Java-style iterators} and \l{STL-style
908 iterators}. STL-style iterators are more efficient and should
911 QMutableMultiMapIterator<Key, T> allows you to iterate over a QMultiMap
912 and modify the map. If you don't want to modify
913 the map (or have a const QMultiMap), use the slightly faster
914 QMultiMapIterator instead.
916 The QMutableMultiMapIterator constructor takes a QMultiMap as argument.
917 After construction, the iterator is located at the very beginning
918 of the map (before the first item). Here's how to iterate over
919 all the elements sequentially:
921 \snippet code/doc_src_qiterator.cpp 32multi
923 The next() function returns the next item in the map and
924 advances the iterator. The key() and value() functions return the
925 key and value of the last item that was jumped over.
927 Unlike STL-style iterators, Java-style iterators point \e between
928 items rather than directly \e at items. The first call to next()
929 advances the iterator to the position between the first and
930 second item, and returns the first item; the second call to
931 next() advances the iterator to the position between the second
932 and third item; and so on.
934 \image javaiterators1.png
936 Here's how to iterate over the elements in reverse order:
938 \snippet code/doc_src_qiterator.cpp 33multi
940 If you want to find all occurrences of a particular value, use
941 findNext() or findPrevious() in a loop. For example:
943 \snippet code/doc_src_qiterator.cpp 34multi
945 If you want to remove items as you iterate over the map, use
946 remove(). If you want to modify the value of an item, use
951 \snippet code/doc_src_qiterator.cpp 35multi
953 The example removes all (key, value) pairs where the key and the
956 Only one mutable iterator can be active on a given map at any
957 time. Furthermore, no changes should be done directly to the map
958 while the iterator is active (as opposed to through the
959 iterator), since this could invalidate the iterator and lead to
962 \sa QMultiMapIterator, QMultiMap::iterator
966 \class QMutableHashIterator
969 \brief The QMutableHashIterator class provides a Java-style non-const iterator for QHash and QMultiHash.
971 QHash has both \l{Java-style iterators} and \l{STL-style
972 iterators}. STL-style iterators are more efficient and should
975 QMutableHashIterator<Key, T> allows you to iterate over a QHash
976 and modify the hash. If you don't want to modify the hash (or have
977 a const QHash), use the slightly faster QHashIterator instead.
979 The QMutableHashIterator constructor takes a QHash as argument.
980 After construction, the iterator is located at the very beginning
981 of the hash (before the first item). Here's how to iterate over
982 all the elements sequentially:
984 \snippet code/doc_src_qiterator.cpp 36
986 The next() function returns the next item in the hash and
987 advances the iterator. The key() and value() functions return the
988 key and value of the last item that was jumped over.
990 Unlike STL-style iterators, Java-style iterators point \e between
991 items rather than directly \e at items. The first call to next()
992 advances the iterator to the position between the first and
993 second item, and returns the first item; the second call to
994 next() advances the iterator to the position between the second
995 and third item; and so on.
997 \image javaiterators1.png
999 If you want to find all occurrences of a particular value, use
1000 findNext() in a loop. For example:
1002 \snippet code/doc_src_qiterator.cpp 38
1004 If you want to remove items as you iterate over the hash, use
1005 remove(). If you want to modify the value of an item, use
1010 \snippet code/doc_src_qiterator.cpp 39
1012 The example removes all (key, value) pairs where the key and the
1015 Only one mutable iterator can be active on a given hash at any
1016 time. Furthermore, no changes should be done directly to the hash
1017 while the iterator is active (as opposed to through the
1018 iterator), since this could invalidate the iterator and lead to
1021 \sa QHashIterator, QHash::iterator
1024/*! \fn template <class Key, class T> QMapIterator<Key, T>::QMapIterator(const QMap<Key, T> &map)
1025 \fn template <class Key, class T> QMutableMapIterator<Key, T>::QMutableMapIterator(QMap<Key, T> &map)
1026 \fn template <class Key, class T> QMultiMapIterator<Key, T>::QMultiMapIterator(const QMultiMap<Key, T> &map)
1027 \fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::QMutableMultiMapIterator(QMultiMap<Key, T> &map)
1029 Constructs an iterator for traversing \a map. The iterator is set
1030 to be at the front of the map (before the first item).
1035/*! \fn template <class Key, class T> QHashIterator<Key, T>::QHashIterator(const QHash<Key, T> &hash)
1036 \fn template <class Key, class T> QMutableHashIterator<Key, T>::QMutableHashIterator(QHash<Key, T> &hash)
1038 Constructs an iterator for traversing \a hash. The iterator is
1039 set to be at the front of the hash (before the first item).
1044/*! \fn template <class Key, class T> QMapIterator &QMapIterator<Key, T>::operator=(const QMap<Key, T> &map)
1045 \fn template <class Key, class T> QMutableMapIterator &QMutableMapIterator<Key, T>::operator=(QMap<Key, T> &map)
1046 \fn template <class Key, class T> QMultiMapIterator &QMultiMapIterator<Key, T>::operator=(const QMultiMap<Key, T> &map)
1047 \fn template <class Key, class T> QMutableMultiMapIterator &QMutableMultiMapIterator<Key, T>::operator=(QMultiMap<Key, T> &map)
1049 Makes the iterator operate on \a map. The iterator is set to be
1050 at the front of the map (before the first item).
1052 \sa toFront(), toBack()
1055/*! \fn template <class Key, class T> QHashIterator &QHashIterator<Key, T>::operator=(const QHash<Key, T> &hash)
1056 \fn template <class Key, class T> QMutableHashIterator &QMutableHashIterator<Key, T>::operator=(QHash<Key, T> &hash)
1058 Makes the iterator operate on \a hash. The iterator is set to be
1059 at the front of the hash (before the first item).
1061 \sa toFront(), toBack()
1064/*! \fn template <class Key, class T> void QMapIterator<Key, T>::toFront()
1065 \fn template <class Key, class T> void QMultiMapIterator<Key, T>::toFront()
1066 \fn template <class Key, class T> void QHashIterator<Key, T>::toFront()
1067 \fn template <class Key, class T> void QMutableMapIterator<Key, T>::toFront()
1068 \fn template <class Key, class T> void QMutableMultiMapIterator<Key, T>::toFront()
1069 \fn template <class Key, class T> void QMutableHashIterator<Key, T>::toFront()
1071 Moves the iterator to the front of the container (before the
1074 \sa toBack(), next()
1077/*! \fn template <class Key, class T> void QMapIterator<Key, T>::toBack()
1078 \fn template <class Key, class T> void QMultiMapIterator<Key, T>::toBack()
1079 \fn template <class Key, class T> void QMutableMapIterator<Key, T>::toBack()
1080 \fn template <class Key, class T> void QMutableMultiMapIterator<Key, T>::toBack()
1082 Moves the iterator to the back of the container (after the last
1085 \sa toFront(), previous()
1089 \fn template <class Key, class T> void QHashIterator<Key, T>::toBack()
1090 \fn template <class Key, class T> void QMutableHashIterator<Key, T>::toBack()
1092 Moves the iterator to the back of the container (after the last
1098/*! \fn template <class Key, class T> bool QMapIterator<Key, T>::hasNext() const
1099 \fn template <class Key, class T> bool QMultiMapIterator<Key, T>::hasNext() const
1100 \fn template <class Key, class T> bool QMutableMapIterator<Key, T>::hasNext() const
1101 \fn template <class Key, class T> bool QMutableMultiMapIterator<Key, T>::hasNext() const
1103 Returns \c true if there is at least one item ahead of the iterator,
1104 i.e. the iterator is \e not at the back of the container;
1105 otherwise returns \c false.
1107 \sa hasPrevious(), next()
1111 \fn template <class Key, class T> bool QHashIterator<Key, T>::hasNext() const
1112 \fn template <class Key, class T> bool QMutableHashIterator<Key, T>::hasNext() const
1114 Returns \c true if there is at least one item ahead of the iterator,
1115 i.e. the iterator is \e not at the back of the container;
1116 otherwise returns \c false.
1121/*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::next()
1122 \fn template <class Key, class T> QMultiMapIterator<Key, T>::Item QMultiMapIterator<Key, T>::next()
1124 Returns the next item and advances the iterator by one position.
1126 Call key() on the return value to obtain the item's key, and
1127 value() to obtain the value.
1129 Calling this function on an iterator located at the back of the
1130 container leads to undefined results.
1132 \sa hasNext(), {QMapIterator::}{peekNext()}, previous()
1135/*! \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::next()
1136 \fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::next()
1138 Returns the next item and advances the iterator by one position.
1140 Call key() on the return value to obtain the item's key, and
1141 value() to obtain the value.
1143 Calling this function on an iterator located at the back of the
1144 container leads to undefined results.
1146 \sa hasNext(), peekNext(), previous()
1150 \fn template <class Key, class T> QHashIterator<Key, T>::Item QHashIterator<Key, T>::next()
1152 Returns the next item and advances the iterator by one position.
1154 Call key() on the return value to obtain the item's key, and
1155 value() to obtain the value.
1157 Calling this function on an iterator located at the back of the
1158 container leads to undefined results.
1160 \sa hasNext(), peekNext()
1164 \fn template <class Key, class T> QMutableHashIterator<Key, T>::Item QMutableHashIterator<Key, T>::next()
1166 Returns the next item and advances the iterator by one position.
1168 Call key() on the return value to obtain the item's key, and
1169 value() to obtain the value.
1171 Calling this function on an iterator located at the back of the
1172 container leads to undefined results.
1174 \sa hasNext(), peekNext()
1177/*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::peekNext() const
1178 \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekNext() const
1180 Returns the next item without moving the iterator.
1182 Call key() on the return value to obtain the item's key, and
1183 value() to obtain the value.
1185 Calling this function on an iterator located at the back of the
1186 container leads to undefined results.
1188 \sa hasNext(), next(), peekPrevious()
1191/*! \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekNext() const
1192 \fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::peekNext() const
1194 Returns a reference to the next item without moving the iterator.
1196 Call key() on the return value to obtain the item's key, and
1197 value() to obtain the value.
1199 Calling this function on an iterator located at the back of the
1200 container leads to undefined results.
1202 \sa hasNext(), next(), peekPrevious()
1206 \fn template <class Key, class T> QHashIterator<Key, T>::Item QHashIterator<Key, T>::peekNext() const
1208 Returns the next item without moving the iterator.
1210 Call key() on the return value to obtain the item's key, and
1211 value() to obtain the value.
1213 Calling this function on an iterator located at the back of the
1214 container leads to undefined results.
1216 \sa hasNext(), next()
1220 \fn template <class Key, class T> QMutableHashIterator<Key, T>::Item QMutableHashIterator<Key, T>::peekNext() const
1222 Returns a reference to the next item without moving the iterator.
1224 Call key() on the return value to obtain the item's key, and
1225 value() to obtain the value.
1227 Calling this function on an iterator located at the back of the
1228 container leads to undefined results.
1230 \sa hasNext(), next()
1233/*! \fn template <class Key, class T> bool QMapIterator<Key, T>::hasPrevious() const
1234 \fn template <class Key, class T> bool QMultiMapIterator<Key, T>::hasPrevious() const
1235 \fn template <class Key, class T> bool QMutableMapIterator<Key, T>::hasPrevious() const
1236 \fn template <class Key, class T> bool QMutableMultiMapIterator<Key, T>::hasPrevious() const
1238 Returns \c true if there is at least one item behind the iterator,
1239 i.e. the iterator is \e not at the front of the container;
1240 otherwise returns \c false.
1242 \sa hasNext(), previous()
1245/*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::previous()
1246 \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::previous()
1247 \fn template <class Key, class T> QMultiMapIterator<Key, T>::Item QMultiMapIterator<Key, T>::previous()
1248 \fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::previous()
1250 Returns the previous item and moves the iterator back by one
1253 Call key() on the return value to obtain the item's key, and
1254 value() to obtain the value.
1256 Calling this function on an iterator located at the front of the
1257 container leads to undefined results.
1259 \sa hasPrevious(), peekPrevious(), next()
1262/*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::peekPrevious() const
1263 \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekPrevious() const
1264 \fn template <class Key, class T> QMultiMapIterator<Key, T>::Item QMultiMapIterator<Key, T>::peekPrevious() const
1265 \fn template <class Key, class T> QMutableMultiMapIterator<Key, T>::Item QMutableMultiMapIterator<Key, T>::peekPrevious() const
1267 Returns the previous item without moving the iterator.
1269 Call key() on the return value to obtain the item's key, and
1270 value() to obtain the value.
1272 Calling this function on an iterator located at the front of the
1273 container leads to undefined results.
1275 \sa hasPrevious(), previous(), {QMapIterator::}{peekNext()}
1278/*! \fn template <class Key, class T> const T &QMapIterator<Key, T>::value() const
1279 \fn template <class Key, class T> const T &QMultiMapIterator<Key, T>::value() const
1281 Returns the value of the last item that was jumped over using one
1282 of the traversal functions (next(), previous(), findNext(),
1285 After a call to next() or findNext(), value() is
1286 equivalent to peekPrevious().value(). After a call to previous()
1287 or findPrevious(), value() is equivalent to peekNext().value().
1293 \fn template <class Key, class T> const T &QMutableMapIterator<Key, T>::value() const
1294 \fn template <class Key, class T> const T &QMutableMultiMapIterator<Key, T>::value() const
1296 Returns the value of the last item that was jumped over using one
1297 of the traversal functions (next(), previous(), findNext(),
1300 After a call to next() or findNext(), value() is
1301 equivalent to peekPrevious().value(). After a call to previous()
1302 or findPrevious(), value() is equivalent to peekNext().value().
1304 \sa key(), setValue()
1307/*! \fn template <class Key, class T> const T &QHashIterator<Key, T>::value() const
1309 Returns the value of the last item that was jumped over using one
1310 of the traversal functions (next(), findNext()).
1316 \fn template <class Key, class T> const T &QMutableHashIterator<Key, T>::value() const
1318 Returns the value of the last item that was jumped over using one
1319 of the traversal functions (next(), findNext()).
1321 \sa key(), setValue()
1325 \fn template <class Key, class T> T &QMutableMapIterator<Key, T>::value()
1326 \fn template <class Key, class T> T &QMutableMultiMapIterator<Key, T>::value()
1327 \fn template <class Key, class T> T &QMutableHashIterator<Key, T>::value()
1330 Returns a non-const reference to the value of
1331 the last item that was jumped over using one
1332 of the traversal functions.
1335/*! \fn template <class Key, class T> const Key &QMapIterator<Key, T>::key() const
1336 \fn template <class Key, class T> const Key &QMutableMapIterator<Key, T>::key() const
1337 \fn template <class Key, class T> const Key &QMultiMapIterator<Key, T>::key() const
1338 \fn template <class Key, class T> const Key &QMutableMultiMapIterator<Key, T>::key() const
1340 Returns the key of the last item that was jumped over using one
1341 of the traversal functions (next(), previous(), findNext(),
1344 After a call to next() or findNext(), key() is
1345 equivalent to peekPrevious().key(). After a call to previous() or
1346 findPrevious(), key() is equivalent to peekNext().key().
1351/*! \fn template <class Key, class T> const Key &QHashIterator<Key, T>::key() const
1352 \fn template <class Key, class T> const Key &QMutableHashIterator<Key, T>::key() const
1354 Returns the key of the last item that was jumped over using one
1355 of the traversal functions (next(), findNext()).
1360/*! \fn template <class Key, class T> bool QMapIterator<Key, T>::findNext(const T &value)
1361 \fn template <class Key, class T> bool QMutableMapIterator<Key, T>::findNext(const T &value)
1362 \fn template <class Key, class T> bool QMultiMapIterator<Key, T>::findNext(const T &value)
1363 \fn template <class Key, class T> bool QMutableMultiMapIterator<Key, T>::findNext(const T &value)
1365 Searches for \a value starting from the current iterator position
1366 forward. Returns \c true if a (key, value) pair with value \a value
1367 is found; otherwise returns \c false.
1369 After the call, if \a value was found, the iterator is positioned
1370 just after the matching item; otherwise, the iterator is
1371 positioned at the back of the container.
1376/*! \fn template <class Key, class T> bool QHashIterator<Key, T>::findNext(const T &value)
1377 \fn template <class Key, class T> bool QMutableHashIterator<Key, T>::findNext(const T &value)
1379 Searches for \a value starting from the current iterator position
1380 forward. Returns \c true if a (key, value) pair with value \a value
1381 is found; otherwise returns \c false.
1383 After the call, if \a value was found, the iterator is positioned
1384 just after the matching item; otherwise, the iterator is
1385 positioned at the back of the container.
1388/*! \fn template <class Key, class T> bool QMapIterator<Key, T>::findPrevious(const T &value)
1389 \fn template <class Key, class T> bool QMutableMapIterator<Key, T>::findPrevious(const T &value)
1390 \fn template <class Key, class T> bool QMultiMapIterator<Key, T>::findPrevious(const T &value)
1391 \fn template <class Key, class T> bool QMutableMultiMapIterator<Key, T>::findPrevious(const T &value)
1393 Searches for \a value starting from the current iterator position
1394 backward. Returns \c true if a (key, value) pair with value \a value
1395 is found; otherwise returns \c false.
1397 After the call, if \a value was found, the iterator is positioned
1398 just before the matching item; otherwise, the iterator is
1399 positioned at the front of the container.
1404/*! \fn template <class Key, class T> void QMutableMapIterator<Key, T>::remove()
1405 \fn template <class Key, class T> void QMutableMultiMapIterator<Key, T>::remove()
1407 Removes the last item that was jumped over using one of the
1408 traversal functions (next(), previous(), findNext(), findPrevious()).
1413/*! \fn template <class Key, class T> void QMutableHashIterator<Key, T>::remove()
1415 Removes the last item that was jumped over using one of the
1416 traversal functions (next(), findNext()).
1421/*! \fn template <class Key, class T> void QMutableMapIterator<Key, T>::setValue(const T &value)
1422 \fn template <class Key, class T> void QMutableMultiMapIterator<Key, T>::setValue(const T &value)
1424 Replaces the value of the last item that was jumped over using
1425 one of the traversal functions with \a value.
1427 The traversal functions are next(), previous(), findNext(), and
1430 \sa key(), value(), remove()
1434 \fn template <class Key, class T> void QMutableHashIterator<Key, T>::setValue(const T &value)
1436 Replaces the value of the last item that was jumped over using
1437 one of the traversal functions with \a value.
1439 The traversal functions are next() and findNext().
1441 \sa key(), value(), remove()