QMultiMap Class

成员函数文档

返回一个范围对象，允许以键/值对的形式迭代此多映射。例如，结合结构化绑定声明，该范围对象可用于基于范围的 for 循环：

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
}

请注意，以这种方式获得的键和值都是多映射中的引用。具体来说，更改值将会修改映射本身。

此函数在 Qt 6.4 中引入。

另请参见 QKeyValueIterator 。

QMultiMap::QMultiMap()

构造一个空的多地图。

另请参见 clear()。

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

如果other 是共享的，则以other 的副本构建多映射。否则，通过移动other 中的元素构建多映射。

此函数在 Qt 6.0 中引入。

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

以other 的副本形式构建一个 multi map。

该函数在 Qt 6.0 中引入。

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

构造other 的副本。

另请参见 toStdMultiMap().

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

构建一个多重映射，其中包含初始化列表list 中每个元素的副本。

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

从other 开始移动，构建多地图。

另请参见 toStdMultiMap().

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

构造other 的副本。

由于 QMultiMap 是隐式共享的，因此该操作在恒定时间内完成。这使得从函数返回 QMultiMap 的速度非常快。如果共享实例被修改，它将被复制（写时复制），这需要线性时间。

另请参见 operator=()。

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

Move- 构造一个 QMultiMap 实例，使其指向other 所指向的同一对象。

[default] QMultiMap::~QMultiMap()

销毁多重映射。多映射中的值引用和多映射上的所有迭代器都将失效。

QMultiMap<Key, T>::iterator QMultiMap::begin()

返回一个STL 样式的迭代器，指向 multi map 中的第一个项目。

另请参阅 constBegin() 和end()。

QMultiMap<Key, T>::const_iterator QMultiMap::begin() const

这是一个重载函数。

QMultiMap<Key, T>::const_iterator QMultiMap::cbegin() const

返回一个常STL 样式的迭代器，指向 multi map 中的第一个项目。

另请参阅 begin() 和cend()。

QMultiMap<Key, T>::const_iterator QMultiMap::cend() const

返回一个常量STL 样式的迭代器，指向多重映射中最后一个项目之后的虚数项目。

另请参阅 cbegin() 和end() 。

void QMultiMap::clear()

删除多地图中的所有项目。

另请参阅 remove()。

QMultiMap<Key, T>::const_iterator QMultiMap::constBegin() const

返回一个常STL 样式的迭代器，指向 multi map 中的第一个项目。

另请参阅 begin() 和constEnd()。

QMultiMap<Key, T>::const_iterator QMultiMap::constEnd() const

返回一个常量STL 样式的迭代器，指向多重映射中最后一个项目之后的虚数项目。

另请参阅 constBegin() 和end() 。

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

返回一个常量迭代器，指向 multi map 中键值为key 的项目。

如果 multi map 中不包含键值为key 的项目，则函数返回constEnd() 。

另请参阅 find() 和 QMultiMap::constFind()。

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

返回一个迭代器，指向 map 中键为key 、值为value 的项目。

如果 map 中没有这样的项目，函数将返回constEnd()。

另请参见 QMap::constFind()。

QMultiMap<Key, T>::const_key_value_iterator QMultiMap::constKeyValueBegin() const

返回指向多映射中第一个条目的STL 样式常量迭代器。

另请参见 keyValueBegin()。

QMultiMap<Key, T>::const_key_value_iterator QMultiMap::constKeyValueEnd() const

返回一个常STL 样式的迭代器，指向多重映射中最后一个条目之后的虚数条目。

另请参见 constKeyValueBegin()。

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

如果 multi map 包含键值为key 的项目，则返回true ；否则返回false 。

另请参阅 count() 。

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

如果 multi map 包含 keykey 和 valuevalue 的项目，则返回true ；否则返回false 。

另请参阅 count() 。

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

返回与关键字key 相关的项目数。

另请参阅 contains() 和QMultiMap::count()。

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

返回关键字为key 且值为value 的项目数。

另请参阅 contains() 和QMultiMap::count()。

QMultiMap<Key, T>::size_type QMultiMap::count() const

这是一个重载函数。

与size() 相同。

bool QMultiMap::empty() const

该函数与 STL 兼容。它等同于isEmpty()，如果映射为空，则返回 true；否则返回 false。

QMultiMap<Key, T>::iterator QMultiMap::end()

返回一个STL 样式的迭代器，指向多重映射中最后一项之后的虚项。

另请参阅 begin() 和constEnd()。

QMultiMap<Key, T>::const_iterator QMultiMap::end() const

这是一个重载函数。

std::pair<QMultiMap<Key, T>::iterator, QMultiMap<Key, T>::iterator> QMultiMap::equal_range(const Key &key)

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

std::pair<QMultiMap<Key, T>::const_iterator, QMultiMap<Key, T>::const_iterator> QMultiMap::equal_range(const Key &key) const

这是一个重载函数。

QMultiMap<Key, T>::iterator QMultiMap::erase(QMultiMap<Key, T>::const_iterator pos)

从 multi map 中删除迭代器pos 指向的（键、值）对，并返回指向 map 中下一项的迭代器。

另请参阅 remove() 。

[since 6.0] QMultiMap<Key, T>::iterator QMultiMap::erase(QMultiMap<Key, T>::const_iterator first, QMultiMap<Key, T>::const_iterator last)

从多重映射中删除迭代器范围 [first,last) 指向的（键、值）对。返回一个迭代器，指向 multi map 中最后一个被移除元素之后的项目。

此函数在 Qt 6.0 中引入。

另请参阅 remove() 。

QMultiMap<Key, T>::iterator QMultiMap::find(const Key &key)

返回一个迭代器，指向 multi map 中键值为key 的项目。

如果 multi map 中不包含键值为key 的项目，则函数返回end() 。

如果多映射中包含多个键值为key 的项目，则该函数返回一个指向最近插入值的迭代器。通过递增迭代器可以访问其他值。例如，下面的代码可以遍历具有相同 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;
}

另请参见 constFind()、value()、values()、lowerBound() 和upperBound()。

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

这是一个重载函数。

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

这是一个重载函数。

返回一个常量迭代器，指向 map 中具有给定key 和value 的项目。

如果 map 中没有这样的项目，函数将返回end() 。

如果 map 中包含多个具有指定key 的项目，则该函数返回一个指向最近插入值的常量迭代器。

T &QMultiMap::first()

返回 multi map 中第一个值的引用，即映射到最小键的值。此函数假定多映射表不为空。

当未共享（或调用 const 版本）时，该函数将在恒定时间内执行。

另请参见 last()、firstKey() 和isEmpty()。

const T &QMultiMap::first() const

这是一个重载函数。

const Key &QMultiMap::firstKey() const

返回 multi map 中最小键的引用。该函数假定多键表不是空的。

执行时间不变。

另请参见 lastKey()、first()、keyBegin() 和isEmpty()。

QMultiMap<Key, T>::iterator QMultiMap::insert(const Key &key, const T &value)

插入一个新项目，其键为key ，值为value 。

如果地图中已经有一个键值相同的项目，该函数将直接创建一个新项目。(这种行为与replace() 不同，后者会覆盖现有项的值。）

返回指向新元素的迭代器。

另请参见 replace()。

QMultiMap<Key, T>::iterator QMultiMap::insert(QMultiMap<Key, T>::const_iterator pos, const Key &key, const T &value)

这是一个重载函数。

插入一个新项目，其键为key ，值为value ，并带有pos 提示，建议在何处插入。

如果使用constBegin() 作为提示，则表示key 小于多重映射中的任何键，而constEnd() 则表示key （严格来说）大于多重映射中的任何键。否则，提示应满足条件 (pos - 1).key() <key <= pos.key().如果提示pos 是错误的，则会被忽略并执行常规插入。

如果提示是正确的，并且多映射是非共享的，则插入将在摊销后的恒定时间内执行。

如果在映射中已经有一个具有相同键值的项目，该函数将直接创建一个新的项目。

当使用constBegin() 从排序数据创建多键映射时，先插入最大键比使用constEnd() 按排序顺序插入要快，因为constEnd() - 1（需要检查提示是否有效）需要对数时间。

返回指向新元素的迭代器。

注意：请小心使用提示。从较早的共享实例中提供迭代器可能会导致程序崩溃，但也有可能无声地损坏多映射和pos 多映射。

bool QMultiMap::isEmpty() const

如果多地图不包含项目，则返回true ；否则返回 false。

另请参阅 size().

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

这是一个重载函数。

返回第一个值为value 的键，如果多映射表中没有值为value 的项，则返回defaultKey 。如果没有提供defaultKey ，函数将返回默认构建的键值。

该函数可能会比较慢（线性时间），因为QMultiMap 的内部数据结构经过优化，可以按键而不是按值快速查找。

另请参见 value() 和keys()。

QMultiMap<Key, T>::key_iterator QMultiMap::keyBegin() const

返回指向多键图中第一个键的STL 样式迭代器。

另请参阅 keyEnd() 和firstKey()。

QMultiMap<Key, T>::key_iterator QMultiMap::keyEnd() const

返回一个常STL 样式的迭代器，指向多键映射中最后一个键之后的虚项。

另请参阅 keyBegin() 和lastKey() 。

QMultiMap<Key, T>::key_value_iterator QMultiMap::keyValueBegin()

返回一个STL 样式的迭代器，指向 multi map 中的第一个条目。

另请参见 keyValueEnd()。

QMultiMap<Key, T>::const_key_value_iterator QMultiMap::keyValueBegin() const

返回指向多映射中第一个条目的STL 样式常量迭代器。

另请参见 keyValueEnd()。

QMultiMap<Key, T>::key_value_iterator QMultiMap::keyValueEnd()

返回一个STL 样式的迭代器，指向多重映射中最后一个条目之后的虚数条目。

另请参见 keyValueBegin()。

QMultiMap<Key, T>::const_key_value_iterator QMultiMap::keyValueEnd() const

返回一个常STL 样式的迭代器，指向多重映射中最后一个条目之后的虚数条目。

另请参见 keyValueBegin()。

QList<Key> QMultiMap::keys() const

以升序返回包含 multi map 中所有键的列表。在多重映射中出现多次的键也会在列表中出现多次。

顺序保证与values() 使用的顺序相同。

该函数以线性时间创建一个新列表。通过从keyBegin() 到keyEnd() 的迭代，可以避免由此产生的时间和内存占用。

另请参见 values() 和key()。

QList<Key> QMultiMap::keys(const T &value) const

这是一个重载函数。

返回一个包含与value 值相关的所有键的列表，以升序排列。

该函数可能会比较慢（线性时间），因为QMultiMap 的内部数据结构经过优化，可以按键而不是按值快速查找。

T &QMultiMap::last()

返回 multi map 中最后一个值的引用，即映射到最大键的值。此函数假定映射表不为空。

当未共享（或调用 const 版本）时，执行时间为对数。

另请参见 first()、lastKey() 和isEmpty()。

const T &QMultiMap::last() const

这是一个重载函数。

const Key &QMultiMap::lastKey() const

返回 multi map 中最大键的引用。此函数假定多键表不是空的。

执行时间为对数。

另请参见 firstKey()、last()、keyEnd() 和isEmpty()。

QMultiMap<Key, T>::iterator QMultiMap::lowerBound(const Key &key)

返回指向地图中第一个键值为key 的项的迭代器。如果 map 中不包含键值为key 的项目，函数将返回一个指向键值更大的最近项目的迭代器。

示例

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

如果映射包含多个键值为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;
}

另请参见 upperBound() 和find()。

QMultiMap<Key, T>::const_iterator QMultiMap::lowerBound(const Key &key) const

这是一个重载函数。

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

从多图标中删除关键字为key 的所有项目。返回删除的项目数。

另请参阅 clear() 和take()。

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

从多映射表中删除键key 和值value 的所有项目。返回删除的项目数。

另请参阅 clear() 和take()。

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

删除多映射中谓词pred 返回 true 的所有元素。

该函数支持使用QMultiMap<Key, T>::iterator 类型参数或std::pair<const Key &, T &> 类型参数的谓词。

如果有，则返回已删除元素的数量。

此函数在 Qt 6.1 中引入。

另请参阅 clear() 和take()。

QMultiMap<Key, T>::iterator QMultiMap::replace(const Key &key, const T &value)

插入一个新项目，其关键字为key ，值为value 。

如果已有一个密钥为key 的项目，则该项目值将被替换为value 。

如果存在多个关键字为key 的项目，则最近插入的项目的值将被替换为value 。

返回指向新/更新元素的迭代器。

另请参阅 insert() 。

QMultiMap<Key, T>::size_type QMultiMap::size() const

返回多映射中（键、值）对的数量。

另请参阅 isEmpty() 和count()。

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

将此多地图与other 互换。该操作速度非常快，从未出现过故障。

T QMultiMap::take(const Key &key)

从多重映射中删除键值为key 的项目，并返回与之相关的值。

如果该项目不存在于多映射中，函数将返回一个默认值。如果映射中有多个key 的项目，则只删除并返回最近插入的项目。

如果不使用返回值，remove() 的效率更高。

另请参阅 remove()。

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

返回等同于此QMultiMap 的 STL 多映射。

QList<Key> QMultiMap::uniqueKeys() const

按升序返回包含映射表中所有键的列表。在映射表中出现多次的键在返回的列表中只出现一次。

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

将other 地图中的所有项目移入此地图。如果两个地图共用一个键，则生成的地图将多次包含该键。

如果other 是共享的，则项目将被复制。

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

将other 地图中的所有项目插入此地图。如果两个地图的关键字相同，则生成的地图将多次包含该关键字。

QMultiMap<Key, T>::iterator QMultiMap::upperBound(const Key &key)

返回一个迭代器，指向紧随映射中最后一个键值为key 的项目。如果 map 中不包含键值为key 的项目，函数将返回一个迭代器，指向最近的键值更大的项目。

示例

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

另请参见 lowerBound() 和find()。

QMultiMap<Key, T>::const_iterator QMultiMap::upperBound(const Key &key) const

这是一个重载函数。

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

返回与键key 相关的值。

如果 multi map 中没有包含 keykey 的项目，函数将返回defaultValue 。如果未指定defaultValue ，函数将返回默认构造值。如果 multi map 中有多个key 项目，则返回最近插入的项目的值。

另请参阅 key()、values() 和contains()。

QList<T> QMultiMap::values() const

按键的升序返回一个包含映射表中所有值的列表。如果一个键与多个值相关联，则其所有值都将出现在列表中，而不仅仅是最近插入的一个。

另请参见 keys() 和value()。

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

返回一个列表，其中包含与 keykey 相关的所有值，从最近插入的值到最近插入的最小值。

另请参阅 keys() 和value()。

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

Move-assignsother 到此QMultiMap 实例。

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

将other 分配给该多地图，并返回对该多地图的引用。