QMap Class

The QMap class is a template class that provides an associative array.

All functions in this class are reentrant.

Article lu fois.

L'auteur

The Qt Company Ltd.

L'article

Publié le 26 janvier 2024 - Mis à jour le 26 janvier 2024

Liens sociaux

QMap Class▲

Header: QMap
CMake:

find_package(Qt6 REQUIRED COMPONENTS Core)

target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Group: QMap is part of tools, Implicitly Shared Classes

Detailed Description▲

QMap<Key, T> is one of Qt's generic container classes. It stores (key, value) pairs and provides fast lookup by key.

QMap and QHash provide very similar functionality. The differences are:

QHash provides average faster lookups than QMap. (See Algorithmic Complexity for details.)
When iterating over a QHash, the items are arbitrarily ordered. With QMap, the items are always sorted by key.
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.

Here's an example QMap with QString keys and int values:

Sélectionnez

QMap&lt;QString, int&gt; map;

To insert a (key, value) pair into the map, you can use operator[]():

Sélectionnez

map["one"] = 1;
map["three"] = 3;
map["seven"] = 7;

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():

Sélectionnez

map.insert("twelve", 12);

To look up a value, use operator[]() or value():

Sélectionnez

int num1 = map["thirteen"];
int num2 = map.value("thirteen");

If there is no item with the specified key in the map, these functions return a default-constructed value.

If you want to check whether the map contains a certain key, use contains():

Sélectionnez

int timeout = 30;
if (map.contains("TIMEOUT"))
    timeout = map.value("TIMEOUT");

There is also a value() overload that uses its second argument as a default value if there is no item with the specified key:

Sélectionnez

int timeout = map.value("TIMEOUT", 30);

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:

Sélectionnez

// WRONG
QMap&lt;int, QWidget *&gt; map;
...
for (int i = 0; i &lt; 1000; ++i) {
    if (map[i] == okButton)
        cout &lt;&lt; "Found button at index " &lt;&lt; i &lt;&lt; Qt::endl;
}

To avoid this problem, replace map[i] with 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 Java-style iterators (QMapIterator and QMutableMapIterator) and STL-style iterators (QMap::const_iterator and QMap::iterator). Here's how to iterate over a QMap<QString, int> using a Java-style iterator:

Sélectionnez

QMapIterator&lt;QString, int&gt; i(map);
while (i.hasNext()) {
    i.next();
    cout &lt;&lt; i.key() &lt;&lt; ": " &lt;&lt; i.value() &lt;&lt; Qt::endl;
}

Here's the same code, but using an STL-style iterator this time:

Sélectionnez

QMap&lt;QString, int&gt;::const_iterator i = map.constBegin();
while (i != map.constEnd()) {
    cout &lt;&lt; i.key() &lt;&lt; ": " &lt;&lt; i.value() &lt;&lt; Qt::endl;
    ++i;
}

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:

Sélectionnez

map.insert("plenty", 100);
map.insert("plenty", 2000);
// map.value("plenty") == 2000

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 foreach:

Sélectionnez

QMap&lt;QString, int&gt; map;
...
foreach (int value, map)
    cout &lt;&lt; value &lt;&lt; Qt::endl;

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 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 x and y are equivalent if neither x < y nor y < x is true.

Example:

Sélectionnez

#ifndef EMPLOYEE_H
#define EMPLOYEE_H

class Employee
{
public:
    Employee() {}
    Employee(const QString &amp;name, QDate dateOfBirth);
    ...

private:
    QString myName;
    QDate myDateOfBirth;
};

inline bool operator&lt;(const Employee &amp;e1, const Employee &amp;e2)
{
    if (e1.name() != e2.name())
        return e1.name() &lt; e2.name();
    return e1.dateOfBirth() &lt; e2.dateOfBirth();
}

#endif // EMPLOYEE_H

In the example, we start by comparing the employees' names. If they're equal, we compare their dates of birth to break the tie.

Member Type Documentation▲

QMap::ConstIterator▲

Qt-style synonym for QMap<Key, T>::const_iterator.

QMap::Iterator▲

Qt-style synonym for QMap<Key, T>::iterator.

[since 5.10] QMap::const_key_value_iterator▲

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.

This typedef was introduced in Qt 5.10.

[alias] QMap::difference_type▲

Typedef for ptrdiff_t. Provided for STL compatibility.

[alias] QMap::key_type▲

Typedef for Key. Provided for STL compatibility.

[since 5.10] QMap::key_value_iterator▲

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.

This typedef was introduced in Qt 5.10.

[alias] QMap::mapped_type▲

Typedef for T. Provided for STL compatibility.

[alias] QMap::size_type▲

Typedef for int. Provided for STL compatibility.

Member Function Documentation▲

[since 6.4] auto QMap::asKeyValueRange() &▲

[since 6.4] auto QMap::asKeyValueRange() &&

[since 6.4] auto QMap::asKeyValueRange() const &

[since 6.4] auto QMap::asKeyValueRange() const &&

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:

Sélectionnez

QMap&lt;QString, int&gt; map;
map.insert("January", 1);
map.insert("February", 2);
// ...
map.insert("December", 12);

for (auto [key, value] : map.asKeyValueRange()) {
    cout &lt;&lt; key &lt;&lt; ": " &lt;&lt; value &lt;&lt; Qt::endl;
    --value; // convert to JS month indexing
}

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.

This function was introduced in Qt 6.4.

QMap::QMap()▲

Constructs an empty map.

[since 5.1] QMap::QMap(std::initializer_list<std::pair<Key, T>> list)▲

Constructs a map with a copy of each of the elements in the initializer list list.

This function was introduced in Qt 5.1.

[explicit] QMap::QMap(const std::map<Key, T> &other)▲

Constructs a copy of other.

[explicit] QMap::QMap(std::map<Key, T> &&other)▲

Constructs a map by moving from other.

[default] QMap::QMap(const QMap<Key, T> &other)▲

Constructs a copy of other.

This operation occurs in constant time, because QMap is 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 linear time.

[default, since 5.2] QMap::QMap(QMap<Key, T> &&other)▲

Move-constructs a QMap instance.

This function was introduced in Qt 5.2.

[default] QMap::~QMap()▲

Destroys the map. References to the values in the map, and all iterators over this map, become invalid.

QMap::iterator QMap::begin()▲

Returns an STL-style iterator pointing to the first item in the map.

QMap::const_iterator QMap::begin() const▲

This is an overloaded function.

[since 5.0] QMap::const_iterator QMap::cbegin() const▲

Returns a const STL-style iterator pointing to the first item in the map.

This function was introduced in Qt 5.0.

[since 5.0] QMap::const_iterator QMap::cend() const▲

Returns a const STL-style iterator pointing to the imaginary item after the last item in the map.

This function was introduced in Qt 5.0.

void QMap::clear()▲

Removes all items from the map.

QMap::const_iterator QMap::constBegin() const▲

Returns a const STL-style iterator pointing to the first item in the map.

QMap::const_iterator QMap::constEnd() const▲

Returns a const STL-style iterator pointing to the imaginary item after the last item in the map.

QMap::const_iterator QMap::constFind(const Key &key) const▲

Returns an const iterator pointing to the item with key key in the map.

If the map contains no item with key key, the function returns constEnd().

[since 5.10] QMap::const_key_value_iterator QMap::constKeyValueBegin() const▲

Returns a const STL-style iterator pointing to the first entry in the map.

This function was introduced in Qt 5.10.

[since 5.10] QMap::const_key_value_iterator QMap::constKeyValueEnd() const▲

Returns a const STL-style iterator pointing to the imaginary entry after the last entry in the map.

This function was introduced in Qt 5.10.

bool QMap::contains(const Key &key) const▲

Returns true if the map contains an item with key key; otherwise returns false.

QMap::size_type QMap::count(const Key &key) const▲

Returns the number of items associated with key key.

QMap::size_type QMap::count() const▲

This is an overloaded function.

Same as size().

bool QMap::empty() const▲

This function is provided for STL compatibility. It is equivalent to isEmpty(), returning true if the map is empty; otherwise returning false.

QMap::iterator QMap::end()▲

Returns an STL-style iterator pointing to the imaginary item after the last item in the map.

QMap::const_iterator QMap::end() const▲

This is an overloaded function.

QPair<QMap::iterator, QMap::iterator> QMap::equal_range(const Key &key)▲

Returns a pair of iterators delimiting the range of values [first, second), that are stored under key.

[since 5.6] QPair<QMap::const_iterator, QMap::const_iterator> QMap::equal_range(const Key &key) const▲

This is an overloaded function.

This function was introduced in Qt 5.6.

QMap::iterator QMap::erase(QMap::const_iterator pos)▲

Removes the (key, value) pair pointed to by the iterator pos from the map, and returns an iterator to the next item in the map.

The iterator pos must be valid and dereferenceable.

[since 6.0] QMap::iterator QMap::erase(QMap::const_iterator first, QMap::const_iterator last)▲

Removes the (key, value) pairs pointed to by the iterator range [first, last) from the map. Returns an iterator to the item in the map following the last removed element.

The range [first, last) must be a valid range in *this.

This function was introduced in Qt 6.0.

QMap::iterator QMap::find(const Key &key)▲

Returns an iterator pointing to the item with key key in the map.

If the map contains no item with key key, the function returns end().

QMap::const_iterator QMap::find(const Key &key) const▲

This is an overloaded function.

[since 5.2] T &QMap::first()▲

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 constant time.

This function was introduced in Qt 5.2.

[since 5.2] const T &QMap::first() const▲

This is an overloaded function.

This function was introduced in Qt 5.2.

[since 5.2] const Key &QMap::firstKey() const▲

Returns a reference to the smallest key in the map. This function assumes that the map is not empty.

This executes in constant time.

This function was introduced in Qt 5.2.

QMap::iterator QMap::insert(const Key &key, const T &value)▲

Inserts a new item with the key key and a value of value.

If there is already an item with the key key, that item's value is replaced with value.

[since 5.1] QMap::iterator QMap::insert(QMap::const_iterator pos, const Key &key, const T &value)▲

This is an overloaded function.

Inserts a new item with the key key and value value and with hint pos suggesting where to do the insert.

If constBegin() is used as hint it indicates that the key is less than any key in the map while constEnd() suggests that the key is (strictly) larger than any key in the map. Otherwise the hint should meet the condition (pos - 1).key() < key <= pos.key(). If the hint pos is wrong it is ignored and a regular insert is done.

If there is already an item with the key key, that item's value is replaced with value.

If the hint is correct and the map is unshared, the insert executes in amortized 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 logarithmic time.

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 pos map.

This function was introduced in Qt 5.1.

[since 5.15] void QMap::insert(const QMap<Key, T> &map)▲

Inserts all the items in map into this map.

If a key is common to both maps, its value will be replaced with the value stored in map.

This function was introduced in Qt 5.15.

[since 5.15] void QMap::insert(QMap<Key, T> &&map)▲

Moves all the items from map into this map.

If a key is common to both maps, its value will be replaced with the value stored in map.

If map is shared, then the items will be copied instead.

This function was introduced in Qt 5.15.

bool QMap::isEmpty() const▲

Returns true if the map contains no items; otherwise returns false.

Key QMap::key(const T &value, const Key &defaultKey = Key()) const▲

This is an overloaded function.

Returns the first key with value value, or defaultKey if the map contains no item with value value. If no defaultKey is provided the function returns a default-constructed key.

This function can be slow (linear time), because QMap's internal data structure is optimized for fast lookup by key, not by value.

[since 5.6] QMap::key_iterator QMap::keyBegin() const▲

Returns a const STL-style iterator pointing to the first key in the map.

This function was introduced in Qt 5.6.

[since 5.6] QMap::key_iterator QMap::keyEnd() const▲

Returns a const STL-style iterator pointing to the imaginary item after the last key in the map.

This function was introduced in Qt 5.6.

[since 5.10] QMap::key_value_iterator QMap::keyValueBegin()▲

Returns an STL-style iterator pointing to the first entry in the map.

This function was introduced in Qt 5.10.

[since 5.10] QMap::const_key_value_iterator QMap::keyValueBegin() const▲

Returns a const STL-style iterator pointing to the first entry in the map.

This function was introduced in Qt 5.10.

[since 5.10] QMap::key_value_iterator QMap::keyValueEnd()▲

Returns an STL-style iterator pointing to the imaginary entry after the last entry in the map.

This function was introduced in Qt 5.10.

[since 5.10] QMap::const_key_value_iterator QMap::keyValueEnd() const▲

Returns a const STL-style iterator pointing to the imaginary entry after the last entry in the map.

This function was introduced in Qt 5.10.

QList<Key> QMap::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 linear time. The time and memory use that entails can be avoided by iterating from keyBegin() to keyEnd().

QList<Key> QMap::keys(const T &value) const▲

This is an overloaded function.

Returns a list containing all the keys associated with value value in ascending order.

This function can be slow (linear time), because QMap's internal data structure is optimized for fast lookup by key, not by value.

[since 5.2] T &QMap::last()▲

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 logarithmic time.

This function was introduced in Qt 5.2.

[since 5.2] const T &QMap::last() const▲

This is an overloaded function.

This function was introduced in Qt 5.2.

[since 5.2] const Key &QMap::lastKey() const▲

Returns a reference to the largest key in the map. This function assumes that the map is not empty.

This executes in logarithmic time.

This function was introduced in Qt 5.2.

QMap::iterator QMap::lowerBound(const Key &key)▲

Returns an iterator pointing to the first item with key key in the map. If the map contains no item with key key, the function returns an iterator to the nearest item with a greater key.

QMap::const_iterator QMap::lowerBound(const Key &key) const▲

This is an overloaded function.

QMap::size_type QMap::remove(const Key &key)▲

Removes all the items that have the key key from the map. Returns the number of items removed which will be 1 if the key exists in the map, and 0 otherwise.

[since 6.1] QMap::size_type QMap::removeIf(Predicate pred)▲

Removes all elements for which the predicate pred returns true from the map.

The function supports predicates which take either an argument of type QMap<Key, T>::iterator, or an argument of type std::pair<const Key &, T &>.

Returns the number of elements removed, if any.

This function was introduced in Qt 6.1.

QMap::size_type QMap::size() const▲

Returns the number of (key, value) pairs in the map.

void QMap::swap(QMap<Key, T> &other)▲

Swaps map other with this map. This operation is very fast and never fails.

T QMap::take(const Key &key)▲

Removes the item with the key 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 default-constructed value.

If you don't use the return value, remove() is more efficient.

std::map<Key, T> QMap::toStdMap() const &▲

Returns an STL map equivalent to this QMap.

[since 6.0] std::map<Key, T> QMap::toStdMap() &&▲

This is an overloaded function.

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.

This function was introduced in Qt 6.0.

QMap::iterator QMap::upperBound(const Key &key)▲

Returns an iterator pointing to the item that immediately follows the last item with key key in the map. If the map contains no item with key key, the function returns an iterator to the nearest item with a greater key.

Example:

Sélectionnez

QMap&lt;int, QString&gt; map;
map.insert(1, "one");
map.insert(5, "five");
map.insert(10, "ten");

map.upperBound(0);      // returns iterator to (1, "one")
map.upperBound(1);      // returns iterator to (5, "five")
map.upperBound(2);      // returns iterator to (5, "five")
map.upperBound(10);     // returns end()
map.upperBound(999);    // returns end()

QMap::const_iterator QMap::upperBound(const Key &key) const▲

This is an overloaded function.

T QMap::value(const Key &key, const T &defaultValue = T()) const▲

Returns the value associated with the key key.

If the map contains no item with key key, the function returns defaultValue. If no defaultValue is specified, the function returns a default-constructed value.

QList<T> QMap::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 linear time. The time and memory use that entails can be avoided by iterating from keyValueBegin() to keyValueEnd().

[default] QMap<Key, T> &QMap::operator=(const QMap<Key, T> &other)▲

Assigns other to this map and returns a reference to this map.

[default, since 5.2] QMap<Key, T> &QMap::operator=(QMap<Key, T> &&other)▲

Move-assigns other to this QMap instance.

This function was introduced in Qt 5.2.

T &QMap::operator[](const Key &key)▲

Returns the value associated with the key key as a modifiable reference.

If the map contains no item with key key, the function inserts a default-constructed value into the map with key key, and returns a reference to it.

T QMap::operator[](const Key &key) const▲

This is an overloaded function.

Same as value().

Related Non-Members▲

[since 6.1] qsizetype erase_if(QMap<Key, T> &map, Predicate pred)▲

Removes all elements for which the predicate pred returns true from the map map.

The function supports predicates which take either an argument of type QMap<Key, T>::iterator, or an argument of type std::pair<const Key &, T &>.

Returns the number of elements removed, if any.

This function was introduced in Qt 6.1.

bool operator!=(const QMap<Key, T> &lhs, const QMap<Key, T> &rhs)▲

Returns true if lhs is not equal to 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 operator==().

QDataStream &operator<<(QDataStream &out, const QMap<Key, T> &map)▲

Writes the map map to stream out.

This function requires the key and value types to implement operator<<().

bool operator==(const QMap<Key, T> &lhs, const QMap<Key, T> &rhs)▲

Returns true if lhs is equal to 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 operator==().

QDataStream &operator>>(QDataStream &in, QMap<Key, T> &map)▲

Reads a map from stream in into map.

This function requires the key and value types to implement operator>>().

QMap Class

L'auteur

L'article

Liens sociaux

QMap Class▲

Detailed Description▲

See Also▲

Member Type Documentation▲

QMap::ConstIterator▲

QMap::Iterator▲

[since 5.10] QMap::const_key_value_iterator▲

See Also▲

[alias] QMap::difference_type▲

[alias] QMap::key_type▲

[since 5.10] QMap::key_value_iterator▲

See Also▲

[alias] QMap::mapped_type▲

[alias] QMap::size_type▲

Member Function Documentation▲

[since 6.4] auto QMap::asKeyValueRange() &▲

See Also▲

QMap::QMap()▲

See Also▲

[since 5.1] QMap::QMap(std::initializer_list<std::pair<Key, T>> list)▲

[explicit] QMap::QMap(const std::map<Key, T> &other)▲

See Also▲

[explicit] QMap::QMap(std::map<Key, T> &&other)▲

See Also▲

[default] QMap::QMap(const QMap<Key, T> &other)▲

See Also▲

[default, since 5.2] QMap::QMap(QMap<Key, T> &&other)▲

[default] QMap::~QMap()▲

QMap::iterator QMap::begin()▲

See Also▲

QMap::const_iterator QMap::begin() const▲

[since 5.0] QMap::const_iterator QMap::cbegin() const▲

See Also▲

[since 5.0] QMap::const_iterator QMap::cend() const▲

See Also▲

void QMap::clear()▲

See Also▲

QMap::const_iterator QMap::constBegin() const▲

See Also▲

QMap::const_iterator QMap::constEnd() const▲

See Also▲

QMap::const_iterator QMap::constFind(const Key &key) const▲

See Also▲

[since 5.10] QMap::const_key_value_iterator QMap::constKeyValueBegin() const▲

See Also▲

[since 5.10] QMap::const_key_value_iterator QMap::constKeyValueEnd() const▲

See Also▲

bool QMap::contains(const Key &key) const▲

See Also▲

QMap::size_type QMap::count(const Key &key) const▲

See Also▲

QMap::size_type QMap::count() const▲

bool QMap::empty() const▲

QMap::iterator QMap::end()▲

See Also▲

QMap::const_iterator QMap::end() const▲

QPair<QMap::iterator, QMap::iterator> QMap::equal_range(const Key &key)▲

[since 5.6] QPair<QMap::const_iterator, QMap::const_iterator> QMap::equal_range(const Key &key) const▲

QMap::iterator QMap::erase(QMap::const_iterator pos)▲

See Also▲

[since 6.0] QMap::iterator QMap::erase(QMap::const_iterator first, QMap::const_iterator last)▲

See Also▲

QMap::iterator QMap::find(const Key &key)▲

See Also▲

QMap::const_iterator QMap::find(const Key &key) const▲

[since 5.2] T &QMap::first()▲

See Also▲

[since 5.2] const T &QMap::first() const▲

[since 5.2] const Key &QMap::firstKey() const▲

See Also▲

QMap::iterator QMap::insert(const Key &key, const T &value)▲

See Also▲

[since 5.1] QMap::iterator QMap::insert(QMap::const_iterator pos, const Key &key, const T &value)▲

See Also▲

[since 5.15] void QMap::insert(const QMap<Key, T> &map)▲

See Also▲