QMap Class

The https:// class is a template class that provides a red-black-tree-based dictionary.

All functions in this class are https://.

Article lu fois.

L'auteur

The Qt Company Ltd.

L'article

Publié le 27 décembre 2024 - Mis à jour le 27 décembre 2024

Liens sociaux

QMap Class▲

Header: QMap
qmake: QT += core
Group: QMap is part of tools, https://

Detailed Description▲

https://<Key, T> is one of Qt's generic https://. It stores (key, value) pairs and provides fast lookup of the value associated with a key.

https:// and https:// provide very similar functionality. The differences are:

https:// provides average faster lookups than https://. (See https:// for details.)
When iterating over a https://, the items are arbitrarily ordered. With https://, the items are always sorted by key.
The key type of a https:// must provide operator==() and a global https://(Key) function. The key type of a https:// 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 https:// 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 https://: ("one", 1), ("three", 3), and ("seven", 7). Another way to insert items into the map is to use https://():

Sélectionnez

map.insert("twelve", 12);

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

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 https://.

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

Sélectionnez

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

There is also a https://() 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 https://() and https://() 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; 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 https://, you can use an iterator. https:// provides both https:// (QMapIterator and https://) and https:// (https:// and https://). Here's how to iterate over a https://<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; 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; endl;
    ++i;
}

The items are traversed in ascending key order.

Normally, a https:// allows only one value per key. If you call https://() with a key that already exists in the https://, 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 https://() instead of https://() (or using the convenience subclass QMultiMap). If you want to retrieve all the values for a single key, you can use values(const Key &key), which returns a https://<T>:

Sélectionnez

QList&lt;int&gt; values = map.values("plenty");
for (int i = 0; i &lt; values.size(); ++i)
    cout &lt;&lt; values.at(i) &lt;&lt; endl;

The items that share the same key are available from most recently to least recently inserted. Another approach is to call https://() to get the STL-style iterator for the first item with a key and iterate from there:

Sélectionnez

QMap&lt;QString, int&gt;::iterator i = map.find("plenty");
while (i != map.end() &amp;&amp; i.key() == "plenty") {
    cout &lt;&lt; i.value() &lt;&lt; endl;
    ++i;
}

If you only need to extract the values from a map (not the keys), you can also use https://:

Sélectionnez

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

Items can be removed from the map in several ways. One way is to call https://(); this will remove any item with the given key. Another way is to use https://(). In addition, you can clear the entire map using https://().

https://'s key and value data types must be https://. 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, https://'s key type must provide operator<(). https:// uses it to keep its items sorted, and assumes that two keys x and y are equal 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, const QDate &amp;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 https://<Key, T>::const_iterator.

QMap::Iterator▲

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

[since 5.10] QMap::const_key_value_iterator▲

The QMap::const_key_value_iterator typedef provides an STL-style iterator for https:// and QMultiMap.

QMap::const_key_value_iterator is essentially the same as https:// with the difference that operator*() returns a key/value pair instead of a value.

This typedef was introduced in Qt 5.10.

QMap::difference_type▲

Typedef for ptrdiff_t. Provided for STL compatibility.

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 https:// and QMultiMap.

QMap::key_value_iterator is essentially the same as https:// with the difference that operator*() returns a key/value pair instead of a value.

This typedef was introduced in Qt 5.10.

QMap::mapped_type▲

Typedef for T. Provided for STL compatibility.

QMap::size_type▲

Typedef for int. Provided for STL compatibility.

Member Function Documentation▲

QMap::QMap()▲

Constructs an empty map.

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

Move-constructs a https:// instance, making it point at the same object that other was pointing to.

This function was introduced in Qt 5.2.

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

Constructs a copy of other.

This operation occurs in https://, because https:// is https://. This makes returning a https:// from a function very fast. If a shared instance is modified, it will be copied (copy-on-write), and this takes https://.

[default] QMap::QMap(const int)▲

Constructs a copy of other.

[default, 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 is only available if the program is being compiled in C++11 mode.

This function was introduced in Qt 5.1.

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 https:// 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 https:// 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 https:// 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 https:// pointing to the first item in the map.

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

Returns a const https:// pointing to the imaginary item after the last item in the map.

[since 4.1] 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 https://().

This function was introduced in Qt 4.1.

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

Returns a const https:// 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 https:// 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.

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

Returns the number of items associated with key key.

int QMap::count() const▲

This is an overloaded function.

Same as https://().

bool QMap::empty() const▲

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

QMap::iterator QMap::end()▲

Returns an https:// 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::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.

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 https://().

If the map contains multiple items with key key, this function returns an iterator that points to the most recently inserted value. The other values are accessible by incrementing the iterator. For example, here's some code that iterates over all the items with the same key:

Sélectionnez

QMap&lt;QString, int&gt; map;
...
QMap&lt;QString, int&gt;::const_iterator i = map.find("HDR");
while (i != map.end() &amp;&amp; i.key() == "HDR") {
    cout &lt;&lt; i.value() &lt;&lt; endl;
    ++i;
}

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 https://.

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 https://.

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.

If there are multiple items with the key key, the most recently inserted 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 https://() is used as hint it indicates that the key is less than any key in the map while https://() suggests that the key is (strictly) larger than any key in the map. Otherwise the hint should meet the condition (pos - 1).https://() < key <= pos.https://(). 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 there are multiple items with the key key, then exactly one of them is replaced with value.

If the hint is correct and the map is unshared, the insert executes in amortized https://.

When creating a map from sorted data inserting the largest key first with https://() is faster than inserting in sorted order with https://(), since https://() - 1 (which is needed to check if the hint is valid) needs https://.

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.

QMap::iterator QMap::insertMulti(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 same key in the map, this function will simply create a new one. (This behavior is different from https://(), which overwrites the value of an existing item.)

[since 5.1] QMap::iterator QMap::insertMulti(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 https://() is used as hint it indicates that the key is less than any key in the map while https://() suggests that the key is larger than any key in the map. Otherwise the hint should meet the condition (pos - 1).https://() < key <= pos.https://(). If the hint pos is wrong it is ignored and a regular https:// is done.

If there is already an item with the same key in the map, this function will simply create a new one.

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.

bool QMap::isEmpty() const▲

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

[since 4.3] const 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 https://.

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

This function was introduced in Qt 4.3.

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

Returns a const https:// 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 https:// 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 https:// 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 https:// 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 https:// 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 https:// 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. Keys that occur multiple times in the map (because items were inserted with https://(), or https://() was used) also occur multiple times in the list.

To obtain a list of unique keys, where each key from the map only occurs once, use https://().

The order is guaranteed to be the same as that used by https://().

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 (https://), because https://'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 https://.

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 https://.

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.

Example:

Sélectionnez

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

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

Sélectionnez

QMap&lt;QString, int&gt; map;
...
QMap&lt;QString, int&gt;::const_iterator i = map.lowerBound("HDR");
QMap&lt;QString, int&gt;::const_iterator upperBound = map.upperBound("HDR");
while (i != upperBound) {
    cout &lt;&lt; i.value() &lt;&lt; endl;
    ++i;
}

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

This is an overloaded function.

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

Removes all the items that have the key key from the map. Returns the number of items removed which is usually 1 but will be 0 if the key isn't in the map, or > 1 if https://() has been used with the key.

int QMap::size() const▲

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

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 https://. If there are multiple items for key in the map, only the most recently inserted one is removed and returned.

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

int QMap::toStdMap() const▲

Returns an STL map equivalent to this https://.

[since 4.2] QList<Key> QMap::uniqueKeys() const▲

This function was introduced in Qt 4.2.

QMap<Key, T> &QMap::unite(const QMap<Key, T> &other)▲

Inserts all the items in the other map into this map. If a key is common to both maps, the resulting map will contain the key multiple times.

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.

const 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 https://. If there are multiple items for key in the map, the value of the most recently inserted one is returned.

QList<T> QMap::values() const▲

Returns a list containing all the values in the map, in ascending order of their keys. If a key is associated with multiple values, all of its values will be in the list, and not just the most recently inserted one.

QList<T> QMap::values(const Key &key) const▲

This is an overloaded function.

Returns a list containing all the values associated with key key, from the most recently inserted to the least recently inserted one.

bool QMap::operator!=(const QMap<Key, T> &other) const▲

Returns true if other is not equal to this map; otherwise returns false.

Two maps are considered equal if they contain the same (key, value) pairs.

This function requires the value type to implement operator==().

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 https:// instance.

This function was introduced in Qt 5.2.

bool QMap::operator==(const QMap<Key, T> &other) const▲

Returns true if other is equal to this map; otherwise returns false.

Two maps are considered equal if they contain the same (key, value) pairs.

This function requires the value type to implement operator==().

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 https:// into the map with key key, and returns a reference to it. If the map contains multiple items with key key, this function returns a reference to the most recently inserted value.

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

This is an overloaded function.

Same as https://().

Related Non-Members▲

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

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▲

QMap::difference_type▲

QMap::key_type▲

[since 5.10] QMap::key_value_iterator▲

See Also▲

QMap::mapped_type▲

QMap::size_type▲

Member Function Documentation▲

QMap::QMap()▲

See Also▲

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

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

See Also▲

[default] QMap::QMap(const int)▲

See Also▲

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

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▲

[since 4.1] 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▲

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

See Also▲

int 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::iterator pos)▲

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▲

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

See Also▲

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

See Also▲

bool QMap::isEmpty() const▲

See Also▲

[since 4.3] const Key QMap::key(const T &value, const Key &defaultKey = Key()) const▲

See Also▲