QMultiMap Class

Detailed Description

The QMultiMap class is a convenience QMap subclass that provides multi-valued maps.

QMultiMap<Key, T> is one of Qt's generic container classes. It inherits QMap and extends it with a few functions that make it able to store multi-valued maps. A multi-valued map is a map that allows multiple values with the same key; QMap doesn't allow that.

Because QMultiMap inherits QMap, all of QMap's functionality also applies to QMultiMap. For example, you can use isEmpty() to test whether the map is empty, and you can traverse a QMultiMap using QMap's iterator classes (for example, QMapIterator). But in addition, it provides an insert() function that inserts but does not overwrite any previous value if the key already exists, and a replace() function that corresponds which does overwite an existing value if they key is already in the map. It also provides convenient operator+() and 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

Unlike QMap, QMultiMap provides no operator[]. Use value() or replace() if you want to access the most recently inserted item with a certain key.

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

If you prefer the STL-style iterators, you can call find() to get the iterator for the first item with a key and iterate from there:

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

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<(). See the QMap documentation for details.