QMultiHash Class

template <typename Key, typename T> class QMultiHash

The QMultiHash class is a convenience QHash subclass that provides multi-valued hashes. More...

Header:	#include <QMultiHash>
CMake:	find_package(Qt6 COMPONENTS Core REQUIRED) target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake:	QT += core

• List of all members, including inherited members

Note: All functions in this class are reentrant.

Public Types

class	const_iterator
class	iterator
class	key_iterator
	const_key_value_iterator
	key_value_iterator

Public Functions

	QMultiHash(const QHash<Key, T> &other)
	QMultiHash(InputIterator begin, InputIterator end)
	QMultiHash(std::initializer_list<std::pair<Key, T> > list)
	QMultiHash()
QMultiHash::iterator	begin()
QMultiHash::const_iterator	begin() const
QMultiHash::const_iterator	cbegin() const
QMultiHash::const_iterator	cend() const
void	clear()
QMultiHash::const_iterator	constBegin() const
QMultiHash::const_iterator	constEnd() const
QMultiHash::const_iterator	constFind(const Key &key, const T &value) const
QMultiHash::const_key_value_iterator	constKeyValueBegin() const
QMultiHash::const_key_value_iterator	constKeyValueEnd() const
bool	contains(const Key &key, const T &value) const
qsizetype	count(const Key &key, const T &value) const
QMultiHash::iterator	emplace(const Key &key, Args &&... args)
QMultiHash::iterator	emplace(Key &&key, Args &&... args)
QMultiHash::iterator	emplaceReplace(const Key &key, Args &&... args)
QMultiHash::iterator	emplaceReplace(Key &&key, Args &&... args)
QMultiHash::iterator	end()
QMultiHash::const_iterator	end() const
QPair<QMultiHash::iterator, QMultiHash::iterator>	equal_range(const Key &key)
QPair<QMultiHash::const_iterator, QMultiHash::const_iterator>	equal_range(const Key &key) const
QMultiHash::iterator	find(const Key &key, const T &value)
QMultiHash::const_iterator	find(const Key &key, const T &value) const
QMultiHash::iterator	insert(const Key &key, const T &value)
Key	key(const T &value, const Key &defaultKey = Key()) const
QMultiHash::key_iterator	keyBegin() const
QMultiHash::key_iterator	keyEnd() const
QMultiHash::key_value_iterator	keyValueBegin()
QMultiHash::const_key_value_iterator	keyValueBegin() const
QMultiHash::key_value_iterator	keyValueEnd()
QMultiHash::const_key_value_iterator	keyValueEnd() const
QList<Key>	keys() const
qsizetype	remove(const Key &key, const T &value)
QMultiHash::iterator	replace(const Key &key, const T &value)
void	swap(QMultiHash<Key, T> &other)
T	take(const Key &key)
QList<Key>	uniqueKeys() const
QMultiHash<Key, T> &	unite(const QMultiHash<Key, T> &other)
QMultiHash<Key, T> &	unite(const QHash<Key, T> &other)
T	value(const Key &key, const T &defaultValue = T()) const
QList<T>	values() const
QList<T>	values(const Key &key) const
QMultiHash<Key, T>	operator+(const QMultiHash<Key, T> &other) const
QMultiHash<Key, T> &	operator+=(const QMultiHash<Key, T> &other)
T &	operator[](const Key &key)

Related Non-Members

size_t	qHash(const QMultiHash<Key, T> &key, size_t seed = 0)
QDataStreamIfHasOStreamOperators<Key, T>	operator<<(QDataStream &out, const QMultiHash<Key, T> &hash)
QDataStreamIfHasIStreamOperators<Key, T>	operator>>(QDataStream &in, QMultiHash<Key, T> &hash)

Detailed Description

QMultiHash<Key, T> is one of Qt's generic container classes. It inherits QHash and extends it with a few convenience functions that make it more suitable than QHash for storing multi-valued hashes. A multi-valued hash is a hash that allows multiple values with the same key.

Because QMultiHash inherits QHash, all of QHash's functionality also applies to QMultiHash. For example, you can use isEmpty() to test whether the hash is empty, and you can traverse a QMultiHash using QHash's iterator classes (for example, QHashIterator). But opposed to QHash, it provides an insert() function will allow the insertion of multiple items with the same key. The replace() function corresponds to QHash::insert(). It also provides convenient operator+() and operator+=().

Unlike QMultiMap, QMultiHash does not provide and ordering of the inserted items. The only guarantee is that items that share the same key will appear consecutively, from the most recently to the least recently inserted value.

Example:

QMultiHash<QString, int> hash1, hash2, hash3;

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

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

hash3 = hash1 + hash2;
// hash3.size() == 3

Unlike QHash, QMultiHash 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 = hash.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.

A more efficient approach is to call find() to get the STL-style iterator for the first item with a key and iterate from there:

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

QMultiHash's key and value data types must be assignable data types. You cannot, for example, store a QWidget as a value; instead, store a QWidget *. In addition, QMultiHash's key type must provide operator==(), and there must also be a qHash() function in the type's namespace that returns a hash value for an argument of the key's type. See the QHash documentation for details.

See also QHash, QHashIterator, QMutableHashIterator, and QMultiMap.

Member Type Documentation

[since 5.10] QMultiHash::const_key_value_iterator

The QMap::const_key_value_iterator typedef provides an STL-style const iterator for QMultiHash and QMultiHash.

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

This typedef was introduced in Qt 5.10.

See also QKeyValueIterator.

[since 5.10] QMultiHash::key_value_iterator

The QMap::key_value_iterator typedef provides an STL-style iterator for QMultiHash and QMultiHash.

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

This typedef was introduced in Qt 5.10.

See also QKeyValueIterator.

Member Function Documentation

Inserts a new element into the container. This new element is constructed in-place using args as the arguments for its construction.

If there is already an item with the same key in the hash, that item's value is replaced with a value constructed from args.

Returns an iterator pointing to the new element.

See also replace and emplace.

Inserts a new element into the container. This new element is constructed in-place using args as the arguments for its construction.

If there is already an item with the same key in the hash, this function will simply create a new one. (This behavior is different from replace(), which overwrites the value of an existing item.)

Returns an iterator pointing to the new element.

See also insert.

QMultiHash::QMultiHash(const QHash<Key, T> &other)

Constructs a copy of other (which can be a QHash or a QMultiHash).

[since 5.14] template <typename InputIterator> QMultiHash::QMultiHash(InputIterator begin, InputIterator end)

Constructs a multi-hash with a copy of each of the elements in the iterator range [begin, end). Either the elements iterated by the range must be objects with first and second data members (like QPair, std::pair, etc.) convertible to Key and to T respectively; or the iterators must have key() and value() member functions, returning a key convertible to Key and a value convertible to T respectively.

This function was introduced in Qt 5.14.

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

Constructs a multi-hash 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.

QMultiHash::QMultiHash()

Constructs an empty hash.

QMultiHash::iterator QMultiHash::begin()

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

See also constBegin() and end().

QMultiHash::const_iterator QMultiHash::begin() const

This is an overloaded function.

[since 5.0] QMultiHash::const_iterator QMultiHash::cbegin() const

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

This function was introduced in Qt 5.0.

See also begin() and cend().

[since 5.0] QMultiHash::const_iterator QMultiHash::cend() const

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

This function was introduced in Qt 5.0.

See also cbegin() and end().

void QMultiHash::clear()

Removes all items from the hash and frees up all memory used by it.

See also remove().

QMultiHash::const_iterator QMultiHash::constBegin() const

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

See also begin() and constEnd().

QMultiHash::const_iterator QMultiHash::constEnd() const

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

See also constBegin() and end().

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

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

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

[since 5.10] QMultiHash::const_key_value_iterator QMultiHash::constKeyValueBegin() const

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

This function was introduced in Qt 5.10.

See also keyValueBegin().

[since 5.10] QMultiHash::const_key_value_iterator QMultiHash::constKeyValueEnd() const

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

This function was introduced in Qt 5.10.

See also constKeyValueBegin().

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

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

See also contains().

qsizetype QMultiHash::count(const Key &key, const T &value) const

Returns the number of items with the key and value.

See also count().

QMultiHash::iterator QMultiHash::end()

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

See also begin() and constEnd().

QMultiHash::const_iterator QMultiHash::end() const

This is an overloaded function.

[since 5.7] QPair<QMultiHash::iterator, QMultiHash::iterator> QMultiHash::equal_range(const Key &key)

Returns a pair of iterators delimiting the range of values [first, second), that are stored under key. If the range is empty then both iterators will be equal to end().

This function was introduced in Qt 5.7.

[since 5.7] QPair<QMultiHash::const_iterator, QMultiHash::const_iterator> QMultiHash::equal_range(const Key &key) const

This is an overloaded function.

This function was introduced in Qt 5.7.

QMultiHash::iterator QMultiHash::find(const Key &key, const T &value)

Returns an iterator pointing to the item with the key and value. If the hash contains no such item, the function returns end().

If the hash contains multiple items with the key and value, the iterator returned points to the most recently inserted item.

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

This is an overloaded function.

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

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

If there is already an item with the same key in the hash, 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().

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

Returns the first key mapped to value, or defaultKey if the hash contains no item mapped to value.

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

[since 5.6] QMultiHash::key_iterator QMultiHash::keyBegin() const

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

This function was introduced in Qt 5.6.

See also keyEnd().

[since 5.6] QMultiHash::key_iterator QMultiHash::keyEnd() const

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

This function was introduced in Qt 5.6.

See also keyBegin().

[since 5.10] QMultiHash::key_value_iterator QMultiHash::keyValueBegin()

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

This function was introduced in Qt 5.10.

See also keyValueEnd().

[since 5.10] QMultiHash::const_key_value_iterator QMultiHash::keyValueBegin() const

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

This function was introduced in Qt 5.10.

See also keyValueEnd().

[since 5.10] QMultiHash::key_value_iterator QMultiHash::keyValueEnd()

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

This function was introduced in Qt 5.10.

See also keyValueBegin().

[since 5.10] QMultiHash::const_key_value_iterator QMultiHash::keyValueEnd() const

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

This function was introduced in Qt 5.10.

See also keyValueBegin().

QList<Key> QMultiHash::keys() const

Returns a list containing all the keys in the hash, in an arbitrary order. Keys that occur multiple times in the hash 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().

qsizetype QMultiHash::remove(const Key &key, const T &value)

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

See also remove().

QMultiHash::iterator QMultiHash::replace(const Key &key, const T &value)

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

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

If there are multiple items with the key, the most recently inserted item's value is replaced with value.

See also insert().

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

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

T QMultiHash::take(const Key &key)

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

If the item does not exist in the hash, the function simply returns a default-constructed value. If there are multiple items for key in the hash, only the most recently inserted one is removed.

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

See also remove().

[since 5.13] QList<Key> QMultiHash::uniqueKeys() const

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

This function was introduced in Qt 5.13.

See also keys() and values().

[since 5.13] QMultiHash<Key, T> &QMultiHash::unite(const QMultiHash<Key, T> &other)

Inserts all the items in the other hash into this hash and returns a reference to this hash.

This function was introduced in Qt 5.13.

See also insert().

[since 6.0] QMultiHash<Key, T> &QMultiHash::unite(const QHash<Key, T> &other)

Inserts all the items in the other hash into this hash and returns a reference to this hash.

This function was introduced in Qt 6.0.

See also insert().

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

This is an overloaded function.

Returns the value associated with the key.

If the hash contains no item with the key, the function returns defaultValue, which is a default-constructed value if the parameter has not been specified.

If there are multiple items for the key in the hash, the value of the most recently inserted one is returned.

QList<T> QMultiHash::values() const

Returns a list containing all the values in the hash, in an arbitrary order. 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.

The order is guaranteed to be the same as that used by 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().

See also keys() and value().

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

This is an overloaded function.

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

See also count() and insert().

QMultiHash<Key, T> QMultiHash::operator+(const QMultiHash<Key, T> &other) const

Returns a hash that contains all the items in this hash in addition to all the items in other. If a key is common to both hashes, the resulting hash will contain the key multiple times.

See also operator+=().

QMultiHash<Key, T> &QMultiHash::operator+=(const QMultiHash<Key, T> &other)

Inserts all the items in the other hash into this hash and returns a reference to this hash.

See also unite() and insert().

T &QMultiHash::operator[](const Key &key)

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

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

If the hash contains multiple items with the key, this function returns a reference to the most recently inserted value.

See also insert() and value().