diff options
Diffstat (limited to 'src/corelib/tools/qmap.qdoc')
| -rw-r--r-- | src/corelib/tools/qmap.qdoc | 1400 |
1 files changed, 1400 insertions, 0 deletions
diff --git a/src/corelib/tools/qmap.qdoc b/src/corelib/tools/qmap.qdoc new file mode 100644 index 0000000000..0cabf3df38 --- /dev/null +++ b/src/corelib/tools/qmap.qdoc @@ -0,0 +1,1400 @@ +// Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com> +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \class QMap + \inmodule QtCore + \brief The QMap class is a template class that provides an associative array. + + \ingroup tools + \ingroup shared + + \reentrant + + QMap\<Key, T\> is one of Qt's generic \l{container classes}. It + stores (key, value) pairs and provides fast lookup by key. + + QMap and QHash provide very similar functionality. The + differences are: + + \list + \li QHash provides average faster lookups than QMap. (See \l{Algorithmic + Complexity} for details.) + \li When iterating over a QHash, the items are arbitrarily ordered. + With QMap, the items are always sorted by key. + \li The key type of a QHash must provide operator==() and a global + qHash(Key) function. The key type of a QMap must provide + operator<() specifying a total order. Since Qt 5.8.1 it is also safe + to use a pointer type as key, even if the underlying operator<() + does not provide a total order. + \endlist + + Here's an example QMap with QString keys and \c int values: + \snippet code/src_corelib_tools_qmap.cpp 0 + + To insert a (key, value) pair into the map, you can use operator[](): + + \snippet code/src_corelib_tools_qmap.cpp 1 + + This inserts the following three (key, value) pairs into the + QMap: ("one", 1), ("three", 3), and ("seven", 7). Another way to + insert items into the map is to use insert(): + + \snippet code/src_corelib_tools_qmap.cpp 2 + + To look up a value, use operator[]() or value(): + + \snippet code/src_corelib_tools_qmap.cpp 3 + + If there is no item with the specified key in the map, these + functions return a \l{default-constructed value}. + + If you want to check whether the map contains a certain key, use + contains(): + + \snippet code/src_corelib_tools_qmap.cpp 4 + + There is also a value() overload that uses its second argument as + a default value if there is no item with the specified key: + + \snippet code/src_corelib_tools_qmap.cpp 5 + + In general, we recommend that you use contains() and value() + rather than operator[]() for looking up a key in a map. The + reason is that operator[]() silently inserts an item into the + map if no item exists with the same key (unless the map is + const). For example, the following code snippet will create 1000 + items in memory: + + \snippet code/src_corelib_tools_qmap.cpp 6 + + To avoid this problem, replace \c map[i] with \c map.value(i) + in the code above. + + If you want to navigate through all the (key, value) pairs stored + in a QMap, you can use an iterator. QMap provides both + \l{Java-style iterators} (QMapIterator and QMutableMapIterator) + and \l{STL-style iterators} (QMap::const_iterator and + QMap::iterator). Here's how to iterate over a QMap<QString, int> + using a Java-style iterator: + + \snippet code/src_corelib_tools_qmap.cpp 7 + + Here's the same code, but using an STL-style iterator this time: + + \snippet code/src_corelib_tools_qmap.cpp 8 + + The items are traversed in ascending key order. + + A QMap allows only one value per key. If you call + insert() with a key that already exists in the QMap, the + previous value will be erased. For example: + + \snippet code/src_corelib_tools_qmap.cpp 9 + + However, you can store multiple values per key by using + QMultiMap. + + If you only need to extract the values from a map (not the keys), + you can also use range-based for: + + \snippet code/src_corelib_tools_qmap.cpp 12 + + Items can be removed from the map in several ways. One way is to + call remove(); this will remove any item with the given key. + Another way is to use QMutableMapIterator::remove(). In addition, + you can clear the entire map using clear(). + + QMap's key and value data types must be \l{assignable data + types}. This covers most data types you are likely to encounter, + but the compiler won't let you, for example, store a QWidget as a + value; instead, store a QWidget *. In addition, QMap's key type + must provide operator<(). QMap uses it to keep its items sorted, + and assumes that two keys \c x and \c y are equivalent if neither \c{x + < y} nor \c{y < x} is true. + + Example: + \snippet code/src_corelib_tools_qmap.cpp 13 + + In the example, we start by comparing the employees' names. If + they're equal, we compare their dates of birth to break the tie. + + \sa QMapIterator, QMutableMapIterator, QHash, QSet +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::QMap() + + Constructs an empty map. + + \sa clear() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::QMap(const QMap<Key, T> &other) + + Constructs a copy of \a other. + + This operation occurs in \l{constant time}, because QMap is + \l{implicitly shared}. This makes returning a QMap from a + function very fast. If a shared instance is modified, it will be + copied (copy-on-write), and this takes \l{linear time}. + + \sa operator= +*/ + +/*! + \fn template <class Key, class T> QMap<Key, T>::QMap(QMap<Key, T> &&other) + + Move-constructs a QMap instance. + + \since 5.2 +*/ + +/*! \fn template <class Key, class T> QMap<Key, T> &QMap<Key, T>::operator=(const QMap<Key, T> &other) + + Assigns \a other to this map and returns a reference to this map. +*/ + +/*! + \fn template <class Key, class T> QMap<Key, T> &QMap<Key, T>::operator=(QMap<Key, T> &&other) + + Move-assigns \a other to this QMap instance. + + \since 5.2 +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::~QMap() + + Destroys the map. References to the values in the map, and all + iterators over this map, become invalid. +*/ + +/*! \fn template <class Key, class T> void QMap<Key, T>::swap(QMap<Key, T> &other) noexcept + \since 4.8 + + Swaps map \a other with this map. This operation is very + fast and never fails. +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::QMap(std::initializer_list<std::pair<Key,T> > list) + \since 5.1 + + Constructs a map with a copy of each of the elements in the + initializer list \a list. +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::QMap(const std::map<Key, T> & other) + + Constructs a copy of \a other. + + \sa toStdMap() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::QMap(std::map<Key, T> && other) + + Constructs a map by moving from \a other. + + \sa toStdMap() +*/ + +/*! \fn template <class Key, class T> std::map<Key, T> QMap<Key, T>::toStdMap() const & + + Returns an STL map equivalent to this QMap. +*/ + +/*! \fn template <class Key, class T> std::map<Key, T> QMap<Key, T>::toStdMap() && + + \overload + \since 6.0 + + \note Calling this function will leave this QMap in the partially-formed state, in which + the only valid operations are destruction or assignment of a new value. +*/ + +/*! \fn template <class Key, class T> bool QMap<Key, T>::operator==(const QMap<Key, T> &lhs, const QMap<Key, T> &rhs) + + Returns \c true if \a lhs is equal to \a rhs; otherwise returns + false. + + Two maps are considered equal if they contain the same (key, + value) pairs. + + This function requires the key and the value types to implement \c + operator==(). + + \sa operator!=() +*/ + +/*! \fn template <class Key, class T> bool QMap<Key, T>::operator!=(const QMap<Key, T> &lhs, const QMap<Key, T> &rhs) + + Returns \c true if \a lhs is not equal to \a rhs; otherwise returns + false. + + Two maps are considered equal if they contain the same (key, + value) pairs. + + This function requires the key and the value types to implement \c + operator==(). + + \sa operator==() +*/ + +/*! \fn template <class Key, class T> size_type QMap<Key, T>::size() const + + Returns the number of (key, value) pairs in the map. + + \sa isEmpty(), count() +*/ + +/*! + \fn template <class Key, class T> bool QMap<Key, T>::isEmpty() const + + Returns \c true if the map contains no items; otherwise returns + false. + + \sa size() +*/ + +/*! \fn template <class Key, class T> void QMap<Key, T>::detach() + + \internal + + Detaches this map from any other maps with which it may share + data. + + \sa isDetached() +*/ + +/*! \fn template <class Key, class T> bool QMap<Key, T>::isDetached() const + + \internal + + Returns \c true if the map's internal data isn't shared with any + other map object; otherwise returns \c false. + + \sa detach() +*/ + +/*! \fn template <class Key, class T> bool QMap<Key, T>::isSharedWith(const QMap<Key, T> &other) const + + \internal +*/ + +/*! \fn template <class Key, class T> void QMap<Key, T>::clear() + + Removes all items from the map. + + \sa remove() +*/ + +/*! \fn template <class Key, class T> size_type QMap<Key, T>::remove(const Key &key) + + Removes all the items that have the key \a key from the map. + Returns the number of items removed which will be 1 if the key + exists in the map, and 0 otherwise. + + \sa clear(), take() +*/ + +/*! \fn template <class Key, class T> template <typename Predicate> size_type QMap<Key, T>::removeIf(Predicate pred) + \since 6.1 + + Removes all elements for which the predicate \a pred returns true + from the map. + + The function supports predicates which take either an argument of + type \c{QMap<Key, T>::iterator}, or an argument of type + \c{std::pair<const Key &, T &>}. + + Returns the number of elements removed, if any. + + \sa clear(), take() +*/ + +/*! \fn template <class Key, class T> T QMap<Key, T>::take(const Key &key) + + Removes the item with the key \a key from the map and returns + the value associated with it. + + If the item does not exist in the map, the function simply + returns a \l{default-constructed value}. + + If you don't use the return value, remove() is more efficient. + + \sa remove() +*/ + +/*! \fn template <class Key, class T> bool QMap<Key, T>::contains(const Key &key) const + + Returns \c true if the map contains an item with key \a key; + otherwise returns \c false. + + \sa count() +*/ + +/*! + \fn template <class Key, class T> Key QMap<Key, T>::key(const T &value, const Key &defaultKey) const + \since 4.3 + \overload + + Returns the first key with value \a value, or \a defaultKey if + the map contains no item with value \a value. If no \a defaultKey + is provided the function returns a + \l{default-constructed value}{default-constructed key}. + + This function can be slow (\l{linear time}), because QMap's + internal data structure is optimized for fast lookup by key, not + by value. + + \sa value(), keys() +*/ + +/*! \fn template <class Key, class T> T QMap<Key, T>::value(const Key &key, const T &defaultValue) const + + Returns the value associated with the key \a key. + + If the map contains no item with key \a key, the function returns + \a defaultValue. If no \a defaultValue is specified, the function + returns a \l{default-constructed value}. + + \sa key(), values(), contains(), operator[]() +*/ + +/*! \fn template <class Key, class T> T &QMap<Key, T>::operator[](const Key &key) + + Returns the value associated with the key \a key as a modifiable + reference. + + If the map contains no item with key \a key, the function inserts + a \l{default-constructed value} into the map with key \a key, and + returns a reference to it. + + \sa insert(), value() +*/ + +/*! \fn template <class Key, class T> T QMap<Key, T>::operator[](const Key &key) const + + \overload + + Same as value(). +*/ + +/*! \fn template <class Key, class T> QList<Key> QMap<Key, T>::keys() const + + Returns a list containing all the keys in the map in ascending + order. + + The order is guaranteed to be the same as that used by values(). + + This function creates a new list, in \l {linear time}. The time and memory + use that entails can be avoided by iterating from \l keyBegin() to + \l keyEnd(). + + \sa values(), key() +*/ + +/*! \fn template <class Key, class T> QList<Key> QMap<Key, T>::keys(const T &value) const + + \overload + + Returns a list containing all the keys associated with value \a + value in ascending order. + + This function can be slow (\l{linear time}), because QMap's + internal data structure is optimized for fast lookup by key, not + by value. +*/ + +/*! \fn template <class Key, class T> QList<T> QMap<Key, T>::values() const + + Returns a list containing all the values in the map, in ascending + order of their keys. + + This function creates a new list, in \l {linear time}. The time and memory + use that entails can be avoided by iterating from \l keyValueBegin() to + \l keyValueEnd(). + + \sa keys(), value() +*/ + +/*! \fn template <class Key, class T> size_type QMap<Key, T>::count(const Key &key) const + + Returns the number of items associated with key \a key. + + \sa contains() +*/ + +/*! \fn template <class Key, class T> size_type QMap<Key, T>::count() const + + \overload + + Same as size(). +*/ + +/*! \fn template <class Key, class T> const Key &QMap<Key, T>::firstKey() const + \since 5.2 + + Returns a reference to the smallest key in the map. + This function assumes that the map is not empty. + + This executes in \l{constant time}. + + \sa lastKey(), first(), keyBegin(), isEmpty() +*/ + +/*! \fn template <class Key, class T> const Key &QMap<Key, T>::lastKey() const + \since 5.2 + + Returns a reference to the largest key in the map. + This function assumes that the map is not empty. + + This executes in \l{logarithmic time}. + + \sa firstKey(), last(), keyEnd(), isEmpty() +*/ + +/*! \fn template <class Key, class T> T &QMap<Key, T>::first() + \since 5.2 + + Returns a reference to the first value in the map, that is the value mapped + to the smallest key. This function assumes that the map is not empty. + + When unshared (or const version is called), this executes in \l{constant time}. + + \sa last(), firstKey(), isEmpty() +*/ + +/*! \fn template <class Key, class T> const T &QMap<Key, T>::first() const + \since 5.2 + + \overload +*/ + +/*! \fn template <class Key, class T> T &QMap<Key, T>::last() + \since 5.2 + + Returns a reference to the last value in the map, that is the value mapped + to the largest key. This function assumes that the map is not empty. + + When unshared (or const version is called), this executes in \l{logarithmic time}. + + \sa first(), lastKey(), isEmpty() +*/ + +/*! \fn template <class Key, class T> const T &QMap<Key, T>::last() const + \since 5.2 + + \overload +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::begin() + + Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first item in + the map. + + \sa constBegin(), end() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::begin() const + + \overload +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::cbegin() const + \since 5.0 + + Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item + in the map. + + \sa begin(), cend() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::constBegin() const + + Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item + in the map. + + \sa begin(), constEnd() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::key_iterator QMap<Key, T>::keyBegin() const + \since 5.6 + + Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first key + in the map. + + \sa keyEnd(), firstKey() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::end() + + Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary item + after the last item in the map. + + \sa begin(), constEnd() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::end() const + + \overload +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::cend() const + \since 5.0 + + Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary + item after the last item in the map. + + \sa cbegin(), end() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::constEnd() const + + Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary + item after the last item in the map. + + \sa constBegin(), end() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::key_iterator QMap<Key, T>::keyEnd() const + \since 5.6 + + Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary + item after the last key in the map. + + \sa keyBegin(), lastKey() +*/ + + +/*! \fn template <class Key, class T> QMap<Key, T>::key_value_iterator QMap<Key, T>::keyValueBegin() + \since 5.10 + + Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first entry + in the map. + + \sa keyValueEnd() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::key_value_iterator QMap<Key, T>::keyValueEnd() + \since 5.10 + + Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary + entry after the last entry in the map. + + \sa keyValueBegin() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_key_value_iterator QMap<Key, T>::keyValueBegin() const + \since 5.10 + + Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry + in the map. + + \sa keyValueEnd() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_key_value_iterator QMap<Key, T>::constKeyValueBegin() const + \since 5.10 + + Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first entry + in the map. + + \sa keyValueBegin() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_key_value_iterator QMap<Key, T>::keyValueEnd() const + \since 5.10 + + Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary + entry after the last entry in the map. + + \sa keyValueBegin() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_key_value_iterator QMap<Key, T>::constKeyValueEnd() const + \since 5.10 + + Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary + entry after the last entry in the map. + + \sa constKeyValueBegin() +*/ + +/*! \fn template <class Key, class T> auto QMap<Key, T>::asKeyValueRange() & + \fn template <class Key, class T> auto QMap<Key, T>::asKeyValueRange() const & + \fn template <class Key, class T> auto QMap<Key, T>::asKeyValueRange() && + \fn template <class Key, class T> auto QMap<Key, T>::asKeyValueRange() const && + \since 6.4 + + Returns a range object that allows iteration over this map as + key/value pairs. For instance, this range object can be used in a + range-based for loop, in combination with a structured binding declaration: + + \snippet code/src_corelib_tools_qmap.cpp 28 + + Note that both the key and the value obtained this way are + references to the ones in the map. Specifically, mutating the value + will modify the map itself. + + \sa QKeyValueIterator +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::erase(const_iterator pos) + + Removes the (key, value) pair pointed to by the iterator \a pos + from the map, and returns an iterator to the next item in the + map. + + \note The iterator \a pos \e must be valid and dereferenceable. + + \sa remove() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::erase(const_iterator first, const_iterator last) + \since 6.0 + + Removes the (key, value) pairs pointed to by the iterator range + [\a first, \a last) from the map. + Returns an iterator to the item in the map following the last removed element. + + \note The range \c {[first, last)} \e must be a valid range in \c {*this}. + + \sa remove() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::find(const Key &key) + + Returns an iterator pointing to the item with key \a key in the + map. + + If the map contains no item with key \a key, the function + returns end(). + + \sa constFind(), value(), values(), lowerBound(), upperBound() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::find(const Key &key) const + + \overload +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::constFind(const Key &key) const + \since 4.1 + + Returns an const iterator pointing to the item with key \a key in the + map. + + If the map contains no item with key \a key, the function + returns constEnd(). + + \sa find() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::lowerBound(const Key &key) + + Returns an iterator pointing to the first item with key \a key in + the map. If the map contains no item with key \a key, the + function returns an iterator to the nearest item with a greater + key. + + \sa upperBound(), find() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::lowerBound(const Key &key) const + + \overload +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::upperBound(const Key &key) + + Returns an iterator pointing to the item that immediately follows + the last item with key \a key in the map. If the map contains no + item with key \a key, the function returns an iterator to the + nearest item with a greater key. + + Example: + \snippet code/src_corelib_tools_qmap.cpp 17 + + \sa lowerBound(), find() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::upperBound(const Key &key) const + + \overload +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::insert(const Key &key, const T &value) + + Inserts a new item with the key \a key and a value of \a value. + + If there is already an item with the key \a key, that item's value + is replaced with \a value. + + Returns an iterator pointing to the new/updated element. +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::insert(const_iterator pos, const Key &key, const T &value) + \overload + \since 5.1 + Inserts a new item with the key \a key and value \a value and with hint \a pos + suggesting where to do the insert. + + If constBegin() is used as hint it indicates that the \a key is less than any key in the map + while constEnd() suggests that the \a key is (strictly) larger than any key in the map. + Otherwise the hint should meet the condition (\a pos - 1).key() < \a key <= pos.key(). + If the hint \a pos is wrong it is ignored and a regular insert is done. + + If there is already an item with the key \a key, that item's value + is replaced with \a value. + + If the hint is correct and the map is unshared, the insert executes in amortized \l{constant time}. + + When creating a map from sorted data inserting the largest key first with constBegin() + is faster than inserting in sorted order with constEnd(), since constEnd() - 1 (which is needed + to check if the hint is valid) needs \l{logarithmic time}. + + \b {Note:} Be careful with the hint. Providing an iterator from an older shared instance might + crash but there is also a risk that it will silently corrupt both the map and the \a pos map. + + Returns an iterator pointing to the new/updated element. +*/ + +/*! \fn template <class Key, class T> void QMap<Key, T>::insert(const QMap<Key, T> &map) + \since 5.15 + + Inserts all the items in \a map into this map. + + If a key is common to both maps, its value will be replaced with + the value stored in \a map. +*/ + +/*! \fn template <class Key, class T> void QMap<Key, T>::insert(QMap<Key, T> &&map) + \since 5.15 + + Moves all the items from \a map into this map. + + If a key is common to both maps, its value will be replaced with + the value stored in \a map. + + If \a map is shared, then the items will be copied instead. +*/ + +/*! \typedef QMap::Iterator + + Qt-style synonym for QMap::iterator. +*/ + +/*! \typedef QMap::ConstIterator + + Qt-style synonym for QMap::const_iterator. +*/ + +/*! \typedef QMap::difference_type + + Typedef for ptrdiff_t. Provided for STL compatibility. +*/ + +/*! \typedef QMap::key_type + + Typedef for Key. Provided for STL compatibility. +*/ + +/*! \typedef QMap::mapped_type + + Typedef for T. Provided for STL compatibility. +*/ + +/*! \typedef QMap::size_type + + Typedef for int. Provided for STL compatibility. +*/ + +/*! + \fn template <class Key, class T> bool QMap<Key, T>::empty() const + + This function is provided for STL compatibility. It is equivalent + to isEmpty(), returning true if the map is empty; otherwise + returning false. +*/ + +/*! + \fn template <class Key, class T> std::pair<typename QMap<Key, T>::iterator, typename QMap<Key, T>::iterator> QMap<Key, T>::equal_range(const Key &key) + + Returns a pair of iterators delimiting the range of values \c{[first, second)}, that + are stored under \a key. +*/ + +/*! + \fn template <class Key, class T> std::pair<typename QMap<Key, T>::const_iterator, typename QMap<Key, T>::const_iterator> QMap<Key, T>::equal_range(const Key &key) const + \overload + \since 5.6 +*/ + + +/*! \class QMap::iterator + \inmodule QtCore + \brief The QMap::iterator class provides an STL-style non-const iterator for QMap. + + QMap\<Key, T\>::iterator allows you to iterate over a QMap + and to modify the value (but not the key) stored under + a particular key. If you want to iterate over a const QMap, you + should use QMap::const_iterator. It is generally good practice to + use QMap::const_iterator on a non-const QMap as well, unless you + need to change the QMap through the iterator. Const iterators are + slightly faster, and can improve code readability. + + The default QMap::iterator constructor creates an uninitialized + iterator. You must initialize it using a QMap function like + QMap::begin(), QMap::end(), or QMap::find() before you can + start iterating. Here's a typical loop that prints all the (key, + value) pairs stored in a map: + + \snippet code/src_corelib_tools_qmap.cpp 18 + + Unlike QHash, which stores its items in an arbitrary order, QMap + stores its items ordered by key. + + Here's an example that increments every value stored in the QMap + by 2: + + \snippet code/src_corelib_tools_qmap.cpp 19 + + To remove elements from a QMap you can use erase_if(QMap\<Key, T\> &map, Predicate pred): + + \snippet code/src_corelib_tools_qmap.cpp 21 + + Multiple iterators can be used on the same map. If you add items + to the map, existing iterators will remain valid. If you remove + items from the map, iterators that point to the removed items + will become dangling iterators. + + \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}. + + \sa QMap::const_iterator, QMap::key_iterator, QMap::key_value_iterator +*/ + +/*! \typedef QMap::iterator::difference_type + + \internal +*/ + +/*! \typedef QMap::iterator::iterator_category + + A synonym for \e {std::bidirectional_iterator_tag} indicating + this iterator is a bidirectional iterator. +*/ + +/*! \typedef QMap::iterator::pointer + + \internal +*/ + +/*! \typedef QMap::iterator::reference + + \internal +*/ + +/*! \typedef QMap::iterator::value_type + + \internal +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::iterator::iterator() + + Constructs an uninitialized iterator. + + Functions like key(), value(), and operator++() must not be + called on an uninitialized iterator. Use operator=() to assign a + value to it before using it. + + \sa QMap::begin(), QMap::end() +*/ + +/*! \fn template <class Key, class T> const Key &QMap<Key, T>::iterator::key() const + + Returns the current item's key as a const reference. + + There is no direct way of changing an item's key through an + iterator, although it can be done by calling QMap::erase() + followed by QMap::insert(). + + \sa value() +*/ + +/*! \fn template <class Key, class T> T &QMap<Key, T>::iterator::value() const + + Returns a modifiable reference to the current item's value. + + You can change the value of an item by using value() on + the left side of an assignment, for example: + + \snippet code/src_corelib_tools_qmap.cpp 23 + + \sa key(), operator*() +*/ + +/*! \fn template <class Key, class T> T &QMap<Key, T>::iterator::operator*() const + + Returns a modifiable reference to the current item's value. + + Same as value(). + + \sa key() +*/ + +/*! \fn template <class Key, class T> T *QMap<Key, T>::iterator::operator->() const + + Returns a pointer to the current item's value. + + \sa value() +*/ + +/*! + \fn template <class Key, class T> bool QMap<Key, T>::iterator::operator==(const iterator &lhs, const iterator &rhs) + \fn template <class Key, class T> bool QMap<Key, T>::const_iterator::operator==(const const_iterator &lhs, const const_iterator &rhs) + + Returns \c true if \a lhs points to the same item as the \a rhs iterator; + otherwise returns \c false. + + \sa operator!=() +*/ + +/*! + \fn template <class Key, class T> bool QMap<Key, T>::iterator::operator!=(const iterator &lhs, const iterator &rhs) + \fn template <class Key, class T> bool QMap<Key, T>::const_iterator::operator!=(const const_iterator &lhs, const const_iterator &rhs) + + Returns \c true if \a lhs points to a different item than the \a rhs iterator; + otherwise returns \c false. + + \sa operator==() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::iterator &QMap<Key, T>::iterator::operator++() + + The prefix \c{++} operator (\c{++i}) advances the iterator to the + next item in the map and returns an iterator to the new current + item. + + Calling this function on QMap::end() leads to undefined results. + + \sa operator--() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator++(int) + + \overload + + The postfix \c{++} operator (\c{i++}) advances the iterator to the + next item in the map and returns an iterator to the previously + current item. +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::iterator &QMap<Key, T>::iterator::operator--() + + The prefix \c{--} operator (\c{--i}) makes the preceding item + current and returns an iterator pointing to the new current item. + + Calling this function on QMap::begin() leads to undefined + results. + + \sa operator++() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator--(int) + + \overload + + The postfix \c{--} operator (\c{i--}) makes the preceding item + current and returns an iterator pointing to the previously + current item. +*/ + +/*! //! friends + \fn [qmap-op-it-plus-step] template <class Key, class T> typename QMap<Key, T>::iterator QMap<Key, T>::iterator::operator+(QMap<Key, T>::iterator, difference_type n) + \fn [qmap-op-step-plus-it] template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator+(difference_type n, QMap<Key, T>::iterator) + \fn [qmap-op-it-minus-step] template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator-(QMap<Key, T>::iterator, difference_type n) + \fn [qmap-op-step-minus-it] template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator-(difference_type n, QMap<Key, T>::iterator) + + //! members + \fn template <class Key, class T> typename QMap<Key, T>::iterator QMap<Key, T>::iterator::operator+=(QMap<Key, T>::iterator::difference_type n) + \fn template <class Key, class T> typename QMap<Key, T>::iterator QMap<Key, T>::iterator::operator-=(QMap<Key, T>::iterator::difference_type n) + + \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead. + + Moves an iterator by \e{n} positions. These operations can be + expensive for large values of \e{n}; QMap iterators are not + random access. +*/ + +/*! \class QMap::const_iterator + \inmodule QtCore + \brief The QMap::const_iterator class provides an STL-style const iterator for QMap. + + QMap\<Key, T\>::const_iterator allows you to iterate over a QMap. + If you want to modify the QMap as you iterate + over it, you must use QMap::iterator instead. It is generally + good practice to use QMap::const_iterator on a non-const QMap as + well, unless you need to change the QMap through the iterator. + Const iterators are slightly faster, and can improve code + readability. + + The default QMap::const_iterator constructor creates an + uninitialized iterator. You must initialize it using a QMap + function like QMap::cbegin(), QMap::cend(), or + QMap::constFind() before you can start iterating. Here's a typical + loop that prints all the (key, value) pairs stored in a map: + + \snippet code/src_corelib_tools_qmap.cpp 24 + + Here's an example that removes all the items whose value is greater than 10: + + \snippet code/src_corelib_tools_qmap.cpp 20 + + And here the same behavior with erase_if() + + \snippet code/src_corelib_tools_qmap.cpp 21 + + Unlike QHash, which stores its items in an arbitrary order, QMap + stores its items ordered by key. + + Multiple iterators can be used on the same map. If you add items + to the map, existing iterators will remain valid. If you remove + items from the map, iterators that point to the removed items + will become dangling iterators. + + \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}. + + \sa QMap::iterator, QMap::key_iterator, QMap::const_key_value_iterator +*/ + +/*! \typedef QMap::const_iterator::difference_type + + \internal +*/ + +/*! \typedef QMap::const_iterator::iterator_category + + A synonym for \e {std::bidirectional_iterator_tag} indicating + this iterator is a bidirectional iterator. +*/ + +/*! \typedef QMap::const_iterator::pointer + + \internal +*/ + +/*! \typedef QMap::const_iterator::reference + + \internal +*/ + +/*! \typedef QMap::const_iterator::value_type + + \internal +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator::const_iterator() + + Constructs an uninitialized iterator. + + Functions like key(), value(), and operator++() must not be + called on an uninitialized iterator. Use operator=() to assign a + value to it before using it. + + \sa QMap::constBegin(), QMap::constEnd() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator::const_iterator(const iterator &other) + + Constructs a copy of \a other. +*/ + +/*! \fn template <class Key, class T> const Key &QMap<Key, T>::const_iterator::key() const + + Returns the current item's key. + + \sa value() +*/ + +/*! \fn template <class Key, class T> const T &QMap<Key, T>::const_iterator::value() const + + Returns the current item's value. + + \sa key(), operator*() +*/ + +/*! \fn template <class Key, class T> const T &QMap<Key, T>::const_iterator::operator*() const + + Returns the current item's value. + + Same as value(). + + \sa key() +*/ + +/*! \fn template <class Key, class T> const T *QMap<Key, T>::const_iterator::operator->() const + + Returns a pointer to the current item's value. + + \sa value() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator &QMap<Key, T>::const_iterator::operator++() + + The prefix \c{++} operator (\c{++i}) advances the iterator to the + next item in the map and returns an iterator to the new current + item. + + Calling this function on QMap::end() leads to undefined results. + + \sa operator--() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator++(int) + + \overload + + The postfix \c{++} operator (\c{i++}) advances the iterator to the + next item in the map and returns an iterator to the previously + current item. +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator &QMap<Key, T>::const_iterator::operator--() + + The prefix \c{--} operator (\c{--i}) makes the preceding item + current and returns an iterator pointing to the new current item. + + Calling this function on QMap::begin() leads to undefined + results. + + \sa operator++() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator--(int) + + \overload + + The postfix \c{--} operator (\c{i--}) makes the preceding item + current and returns an iterator pointing to the previously + current item. +*/ + +/*! //! friends + \fn [qmap-op-it-plus-step-const] template <class Key, class T> QMap<Key, T>::const_iterator::operator+(QMap<Key, T>::const_iterator, difference_type n) + \fn [qmap-op-step-plus-it-const] template <class Key, class T> QMap<Key, T>::operator+(difference_type n, QMap<Key, T>::const_iterator) + \fn [qmap-op-it-minus-step-const] template <class Key, class T> QMap<Key, T>::operator-(QMap<Key, T>::const_iterator, difference_type n) + \fn [qmap-op-step-minus-it-const] template <class Key, class T> QMap<Key, T>::operator-(difference_type n, QMap<Key, T>::const_iterator) + + //! members + \fn template <class Key, class T> typename QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator+=(QMap<Key, T>::const_iterator::difference_type n) + \fn template <class Key, class T> typename QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator-=(QMap<Key, T>::const_iterator::difference_type n) + + \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead. + + Moves an iterator by \e{n} positions. These operations can be + expensive for large values of \e{n}. QMap iterators are not + random access. +*/ + +/*! \class QMap::key_iterator + \inmodule QtCore + \since 5.6 + \brief The QMap::key_iterator class provides an STL-style const iterator for QMap keys. + + QMap::key_iterator is essentially the same as QMap::const_iterator + with the difference that operator*() and operator->() return a key + instead of a value. + + For most uses QMap::iterator and QMap::const_iterator should be used, + you can easily access the key by calling QMap::iterator::key(): + + \snippet code/src_corelib_tools_qmap.cpp keyiterator1 + + However, to have interoperability between QMap's keys and STL-style + algorithms we need an iterator that dereferences to a key instead + of a value. With QMap::key_iterator we can apply an algorithm to a + range of keys without having to call QMap::keys(), which is inefficient + as it costs one QMap iteration and memory allocation to create a temporary + QList. + + \snippet code/src_corelib_tools_qmap.cpp keyiterator2 + + QMap::key_iterator is const, it's not possible to modify the key. + + The default QMap::key_iterator constructor creates an uninitialized + iterator. You must initialize it using a QMap function like + QMap::keyBegin() or QMap::keyEnd(). + + \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}. + + \sa QMap::const_iterator, QMap::iterator +*/ + +/*! \typedef QMap::key_iterator::difference_type + \internal +*/ + +/*! \typedef QMap::key_iterator::iterator_category + \internal +*/ + +/*! \typedef QMap::key_iterator::pointer + \internal +*/ + +/*! \typedef QMap::key_iterator::reference + \internal +*/ + +/*! \typedef QMap::key_iterator::value_type + \internal +*/ + +/*! \fn template <class Key, class T> const T &QMap<Key, T>::key_iterator::operator*() const + + Returns the current item's key. +*/ + +/*! \fn template <class Key, class T> const T *QMap<Key, T>::key_iterator::operator->() const + + Returns a pointer to the current item's key. +*/ + +/*! \fn template <class Key, class T> bool QMap<Key, T>::key_iterator::operator==(key_iterator other) const + + Returns \c true if \a other points to the same item as this + iterator; otherwise returns \c false. + + \sa operator!=() +*/ + +/*! \fn template <class Key, class T> bool QMap<Key, T>::key_iterator::operator!=(key_iterator other) const + + Returns \c true if \a other points to a different item than this + iterator; otherwise returns \c false. + + \sa operator==() +*/ + +/*! + \fn template <class Key, class T> QMap<Key, T>::key_iterator &QMap<Key, T>::key_iterator::operator++() + + The prefix \c{++} operator (\c{++i}) advances the iterator to the + next item in the hash and returns an iterator to the new current + item. + + Calling this function on QMap::keyEnd() leads to undefined results. + + \sa operator--() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::key_iterator QMap<Key, T>::key_iterator::operator++(int) + + \overload + + The postfix \c{++} operator (\c{i++}) advances the iterator to the + next item in the hash and returns an iterator to the previous + item. +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::key_iterator &QMap<Key, T>::key_iterator::operator--() + + The prefix \c{--} operator (\c{--i}) makes the preceding item + current and returns an iterator pointing to the new current item. + + Calling this function on QMap::keyBegin() leads to undefined + results. + + \sa operator++() +*/ + +/*! \fn template <class Key, class T> QMap<Key, T>::key_iterator QMap<Key, T>::key_iterator::operator--(int) + + \overload + + The postfix \c{--} operator (\c{i--}) makes the preceding item + current and returns an iterator pointing to the previous + item. +*/ + +/*! \fn template <class Key, class T> const_iterator QMap<Key, T>::key_iterator::base() const + Returns the underlying const_iterator this key_iterator is based on. +*/ + +/*! \typedef QMap::const_key_value_iterator + \inmodule QtCore + \since 5.10 + \brief The QMap::const_key_value_iterator typedef provides an STL-style iterator for QMap. + + QMap::const_key_value_iterator is essentially the same as QMap::const_iterator + with the difference that operator*() returns a key/value pair instead of a + value. + + \sa QKeyValueIterator +*/ + +/*! \typedef QMap::key_value_iterator + \inmodule QtCore + \since 5.10 + \brief The QMap::key_value_iterator typedef provides an STL-style iterator for QMap. + + QMap::key_value_iterator is essentially the same as QMap::iterator + with the difference that operator*() returns a key/value pair instead of a + value. + + \sa QKeyValueIterator +*/ + +/*! \fn template <class Key, class T> QDataStream &operator<<(QDataStream &out, const QMap<Key, T> &map) + \relates QMap + + Writes the map \a map to stream \a out. + + This function requires the key and value types to implement \c + operator<<(). + + \sa{Serializing Qt Data Types}{Format of the QDataStream operators} +*/ + +/*! \fn template <class Key, class T> QDataStream &operator>>(QDataStream &in, QMap<Key, T> &map) + \relates QMap + + Reads a map from stream \a in into \a map. + + This function requires the key and value types to implement \c + operator>>(). + + \sa{Serializing Qt Data Types}{Format of the QDataStream operators} +*/ + +/*! \fn template <typename Key, typename T, typename Predicate> qsizetype erase_if(QMap<Key, T> &map, Predicate pred) + \relates QMap + \since 6.1 + + Removes all elements for which the predicate \a pred returns true + from the map \a map. + + The function supports predicates which take either an argument of + type \c{QMap<Key, T>::iterator}, or an argument of type + \c{std::pair<const Key &, T &>}. + + Returns the number of elements removed, if any. +*/ + +/*! + \fn template <class Key, class T> size_t QMap<Key, T>::qHash(const QMap &key, size_t seed) noexcept + \since 6.8 + + Returns the hash value for \a key, using \a seed to seed the calculation. + + Types \c Key and \c T must be supported by qHash(). +*/ |