QMultiMap Class

Member Function Documentation

Returns a range object that allows iteration over this multi 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:

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

for (auto [key, value] : map.asKeyValueRange()) {
    cout << qPrintable(key) << ": " << value << 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 multi map. Specifically, mutating the value will modify the map itself.

This function was introduced in Qt 6.4.

See also QKeyValueIterator.

QMultiMap::QMultiMap()

Constructs an empty multi map.

See also clear().

QMultiMap::QMultiMap(std::initializer_list<std::pair<Key, T>> list)

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

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

Constructs a multi map as a copy of other.

This function was introduced in Qt 6.0.

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

If other is shared, constructs a multi map as a copy of other. Otherwise, constructs a multi map by moving the elements from other.

This function was introduced in Qt 6.0.

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

Constructs a copy of other.

See also toStdMultiMap().

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

Constructs a multi map by moving from other.

See also toStdMultiMap().

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

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

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

Constructs a copy of other.

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

See also operator=().

[default] QMultiMap::~QMultiMap()

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

QMultiMap::iterator QMultiMap::begin()

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

See also constBegin() and end().

QMultiMap::const_iterator QMultiMap::begin() const

This is an overloaded function.

QMultiMap::const_iterator QMultiMap::cbegin() const

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

See also begin() and cend().

QMultiMap::const_iterator QMultiMap::cend() const

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

See also cbegin() and end().

void QMultiMap::clear()

Removes all items from the multi map.

See also remove().

QMultiMap::const_iterator QMultiMap::constBegin() const

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

See also begin() and constEnd().

QMultiMap::const_iterator QMultiMap::constEnd() const

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

See also constBegin() and end().

QMultiMap::const_iterator QMultiMap::constFind(const Key &key) const

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

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

See also find() and QMultiMap::constFind().

QMultiMap::const_iterator QMultiMap::constFind(const Key &key, const T &value) const

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

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

See also QMap::constFind().

QMultiMap::const_key_value_iterator QMultiMap::constKeyValueBegin() const

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

See also keyValueBegin().

QMultiMap::const_key_value_iterator QMultiMap::constKeyValueEnd() const

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

See also constKeyValueBegin().

bool QMultiMap::contains(const Key &key) const

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

See also count().

bool QMultiMap::contains(const Key &key, const T &value) const

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

See also count().

QMultiMap::size_type QMultiMap::count(const Key &key) const

Returns the number of items associated with key key.

See also contains() and QMultiMap::count().

QMultiMap::size_type QMultiMap::count(const Key &key, const T &value) const

Returns the number of items with key key and value value.

See also contains() and QMultiMap::count().

QMultiMap::size_type QMultiMap::count() const

This is an overloaded function.

Same as size().

bool QMultiMap::empty() const

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

QMultiMap::iterator QMultiMap::end()

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

See also begin() and constEnd().

QMultiMap::const_iterator QMultiMap::end() const

This is an overloaded function.

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

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

QPair<QMultiMap::const_iterator, QMultiMap::const_iterator> QMultiMap::equal_range(const Key &key) const

This is an overloaded function.

QMultiMap::iterator QMultiMap::erase(QMultiMap::const_iterator pos)

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

See also remove().

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

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

This function was introduced in Qt 6.0.

See also remove().

QMultiMap::iterator QMultiMap::find(const Key &key)

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

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

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:

auto i = multimap.find("plenty");
while (i != map.end() && i.key() == "plenty") {
    cout << i.value() << endl;
    ++i;
}

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

See also constFind(), value(), values(), lowerBound(), and upperBound().

QMultiMap::const_iterator QMultiMap::find(const Key &key) const

This is an overloaded function.

QMultiMap::const_iterator QMultiMap::find(const Key &key, const T &value) const

This is an overloaded function.

Returns a const iterator pointing to the item with the given key and value in the map.

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

If the map contains multiple items with the specified key, this function returns a const iterator that points to the most recently inserted value.

T &QMultiMap::first()

Returns a reference to the first value in the multi map, that is the value mapped to the smallest key. This function assumes that the multi map is not empty.

When unshared (or const version is called), this executes in constant time.

See also last(), firstKey(), and isEmpty().

const T &QMultiMap::first() const

This is an overloaded function.

const Key &QMultiMap::firstKey() const

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

This executes in constant time.

See also lastKey(), first(), keyBegin(), and isEmpty().

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

See also replace().

QMultiMap::iterator QMultiMap::insert(QMultiMap::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 multi map while constEnd() suggests that the key is (strictly) larger than any key in the multi 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 the hint is correct and the multi map is unshared, the insert executes in amortized constant time.

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

When creating a multi 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 multi map and the pos multi map.

bool QMultiMap::isEmpty() const

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

See also size().

Key QMultiMap::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 multi 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 QMultiMap's internal data structure is optimized for fast lookup by key, not by value.

See also value() and keys().

QMultiMap::key_iterator QMultiMap::keyBegin() const

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

See also keyEnd() and firstKey().

QMultiMap::key_iterator QMultiMap::keyEnd() const

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

See also keyBegin() and lastKey().

QMultiMap::key_value_iterator QMultiMap::keyValueBegin()

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

See also keyValueEnd().

QMultiMap::const_key_value_iterator QMultiMap::keyValueBegin() const

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

See also keyValueEnd().

QMultiMap::key_value_iterator QMultiMap::keyValueEnd()

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

See also keyValueBegin().

QMultiMap::const_key_value_iterator QMultiMap::keyValueEnd() const

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

See also keyValueBegin().

QList<Key> QMultiMap::keys() const

Returns a list containing all the keys in the multi map in ascending order. Keys that occur multiple times in the multi map also occur multiple times in the list.

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

See also values() and key().

QList<Key> QMultiMap::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 QMultiMap's internal data structure is optimized for fast lookup by key, not by value.

T &QMultiMap::last()

Returns a reference to the last value in the multi 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.

See also first(), lastKey(), and isEmpty().

const T &QMultiMap::last() const

This is an overloaded function.

const Key &QMultiMap::lastKey() const

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

This executes in logarithmic time.

See also firstKey(), last(), keyEnd(), and isEmpty().

QMultiMap::iterator QMultiMap::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:

QMultiMap<int, QString> multimap;
multimap.insert(1, "one");
multimap.insert(5, "five");
multimap.insert(5, "five (2)");
multimap.insert(10, "ten");

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

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:

QMap<QString, int> multimap;
...
QMap<QString, int>::const_iterator i = multimap.lowerBound("HDR");
QMap<QString, int>::const_iterator upperBound = multimap.upperBound("HDR");
while (i != upperBound) {
    cout << i.value() << endl;
    ++i;
}

See also upperBound() and find().

QMultiMap::const_iterator QMultiMap::lowerBound(const Key &key) const

This is an overloaded function.

QMultiMap::size_type QMultiMap::remove(const Key &key)

Removes all the items that have the key key from the multi map. Returns the number of items removed.

See also clear() and take().

QMultiMap::size_type QMultiMap::remove(const Key &key, const T &value)

Removes all the items that have the key key and value value from the multi map. Returns the number of items removed.

See also clear() and take().

[since 6.1] template <typename Predicate> QMultiMap::size_type QMultiMap::removeIf(Predicate pred)

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

The function supports predicates which take either an argument of type QMultiMap<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.

See also clear() and take().

QMultiMap::iterator QMultiMap::replace(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.

See also insert().

QMultiMap::size_type QMultiMap::size() const

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

See also isEmpty() and count().

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

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

T QMultiMap::take(const Key &key)

Removes the item with the key key from the multi map and returns the value associated with it.

If the item does not exist in the multi map, the function simply returns a default-constructed value. 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, remove() is more efficient.

See also remove().

std::multimap<Key, T> QMultiMap::toStdMultiMap() const &

Returns an STL multi map equivalent to this QMultiMap.

QList<Key> QMultiMap::uniqueKeys() const

Returns a list containing all the keys in the map in ascending order. Keys that occur multiple times in the map occur only once in the returned list.

QMultiMap<Key, T> &QMultiMap::unite(const QMultiMap<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.

QMultiMap<Key, T> &QMultiMap::unite(QMultiMap<Key, T> &&other)

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

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

QMultiMap::iterator QMultiMap::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:

QMultiMap<int, QString> multimap;
multimap.insert(1, "one");
multimap.insert(5, "five");
multimap.insert(5, "five (2)");
multimap.insert(10, "ten");

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

See also lowerBound() and find().

QMultiMap::const_iterator QMultiMap::upperBound(const Key &key) const

This is an overloaded function.

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

Returns the value associated with the key key.

If the multi map contains no item with key key, the function returns defaultValue. If no defaultValue is specified, the function returns a default-constructed value. If there are multiple items for key in the multi map, the value of the most recently inserted one is returned.

See also key(), values(), and contains().

QList<T> QMultiMap::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.

See also keys() and value().

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

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

See also keys() and value().

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

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

[default] QMultiMap<Key, T> &QMultiMap::operator=(QMultiMap<Key, T> &&other)

Move-assigns other to this QMultiMap instance.