QMultiMap Class

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

QMultiMap and QMultiHash provide very similar functionality. The differences are:

• QMultiHash provides average faster lookups than QMultiMap. (See Algorithmic Complexity for details.)

• When iterating over a QMultiHash, the items are arbitrarily ordered. With QMultiMap, the items are always sorted by key.

• The key type of a QMultiHash must provide operator==() and a global qHash(Key) function. The key type of a QMultiMap 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 QMultiMap with QString keys and int values:

QMultiMap<QString, int> multimap;

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

multimap.insert("a", 1);
multimap.insert("b", 3);
multimap.insert("c", 7);
multimap.insert("c", -5);

This inserts the following three (key, value) pairs into the QMultiMap: ("a", 1), ("b", 3), ("c", 7), and ("c", -5); note that duplicate keys are allowed.

To look up a value, use find() or value():

int num2 = multimap.value("a"); // 1
int num3 = multimap.value("thirteen"); // not found; 0
int num3 = 0;
auto it = multimap.value("b");
if (it != multimap.end()) {
    num3 = it.value();
}

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

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

// better:
auto it = multimap.find("TIMEOUT");
if (it != multimap.end())
    timeout = it.value();

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

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

If you want to navigate through all the (key, value) pairs stored in a QMultiMap, you can use an iterator. QMultiMap provides both Java-style iterators (QMultiMapIterator and QMutableMultiMapIterator) and STL-style iterators (QMultiMap::const_iterator and QMultiMap::iterator). Here's how to iterate over a QMultiMap<QString, int> using a Java-style iterator:

QMultiMapIterator<QString, int> i(multimap);
while (i.hasNext()) {
    i.next();
    cout << i.key() << ": " << i.value() << Qt::endl;
}

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

auto i = multimap.constBegin();
while (i != multimap.constEnd()) {
    cout << i.key() << ": " << i.value() << Qt::endl;
    ++i;
}

The items are traversed in ascending key order.

A QMultiMap allows multiple values per key. If you call insert() with a key that already exists in the map, a new (key, value) pair will be inserted. For example:

multimap.insert("plenty", 100);
multimap.insert("plenty", 2000);
// multimap.size() == 2

If you want to retrieve all the values for a single key, you can use values(const Key &key), which returns a QList<T>:

QList<int> values = multimap.values("plenty");
for (int i = 0; i < values.size(); ++i)
    cout << values.at(i) << Qt::endl;

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

QMultiMap<QString, int>::iterator i = multimap.find("plenty");
while (i != map.end() && i.key() == "plenty") {
    cout << i.value() << Qt::endl;
    ++i;
}

// better:
auto [i, end] = multimap.equal_range("plenty");
while (i != end) {
    cout << i.value() << Qt::endl;
    ++i;
}

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

QMap<QString, int> multimap;
...
foreach (int value, multimap)
    cout << value << Qt::endl;

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

It is possible to merge two multi maps by calling unite(), by using operator+(), and by using operator+=(). Example:

QMultiMap<QString, int> map1, map2, map3;

map1.insert("plenty", 100);
map1.insert("plenty", 2000);
// map1.size() == 2

map2.insert("plenty", 5000);
// map2.size() == 1

map3 = map1 + map2;
// map3.size() == 3

QMultiMap'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, QMultiMap's key type must provide operator<(). QMap 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:

#ifndef EMPLOYEE_H
#define EMPLOYEE_H

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

private:
    QString myName;
    QDate myDateOfBirth;
};

inline bool operator<(const Employee &e1, const Employee &e2)
{
    if (e1.name() != e2.name())
        return e1.name() < e2.name();
    return e1.dateOfBirth() < 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.

See Also▲

QMultiMap::ConstIterator▲

QMultiMap::Iterator▲

[since 5.10] QMultiMap::const_key_value_iterator▲

[alias] QMultiMap::difference_type▲

[alias] QMultiMap::key_type▲

[since 5.10] QMultiMap::key_value_iterator▲

[alias] QMultiMap::mapped_type▲

[alias] QMultiMap::size_type▲

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

QMultiMap<QString, int> map;
map.insert("January", 1);
map.insert("February", 2);
// ...
map.insert("December", 12);

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

QMultiMap::QMultiMap()▲

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

[explicit, since 6.0] QMultiMap::QMultiMap(const QMap<Key, T> &other)▲

[explicit, since 6.0] QMultiMap::QMultiMap(QMap<Key, T> &&other)▲

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

[explicit] QMultiMap::QMultiMap(std::multimap<Key, T> &&other)▲

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

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

[default] QMultiMap::~QMultiMap()▲

QMultiMap::iterator QMultiMap::begin()▲