QMultiMap Class

成员函数文档

[default] 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 的副本。

该函数在 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()。

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

构建other 的副本。

由于 QMultiMap 是隐式共享的，因此该操作的时间复杂度为常数。这使得从函数中返回一个 QMultiMap 非常快。如果共享实例被修改，它将被复制（写时复制），而此操作的时间复杂度为线性。

另请参阅 operator=()。

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

通过“move”操作构造一个 QMultiMap 实例，使其指向与other 所指向的同一对象。

[implicit] QMultiMap::~QMultiMap()

销毁多映射。对多映射中值的引用以及所有遍历该多映射的迭代器都将失效。

返回一个范围对象，允许以键值对的形式遍历此多映射。例如，该范围对象可与结构化绑定声明结合使用，在基于范围的 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<Key, T>::iterator QMultiMap::begin()

返回一个指向多映射中第一个项的STL 风格迭代器。

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

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

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

返回一个指向多映射中第一个元素的常量STL 风格迭代器。

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

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

返回一个指向多映射中最后一个元素之后的“虚”元素的、STL 风格的const迭代器。

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

void QMultiMap::clear()

从多映射中移除所有项目。

另请参阅 remove()。

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

返回一个指向多映射中第一个项的 constSTL 风格迭代器。

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

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

返回一个指向多映射中最后一个元素之后的虚拟元素的常量STL 风格迭代器。

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

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

返回一个指向多映射中键为key 的项的const迭代器。

如果多映射中不存在键为key 的项，则该函数返回constEnd()。

另请参见 find() 和QMultiMap::constFind(const Key &key, const T &value)。

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

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

如果映射中不存在该项，则该函数返回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 风格的const迭代器。

另请参阅 constKeyValueBegin()。

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

如果多映射中包含键为key 的条目，则返回true ；否则返回false 。

另请参阅 count()。

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

如果多映射中包含键为key 、值为value 的条目，则返回true ；否则返回false 。

另请参阅 count()。

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

返回与键key 关联的项的数量。

另请参阅 contains() 和QMultiMap::count(const Key &key, const T &value)。

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)

返回一对迭代器，它们界定了值范围[first, second) ，这些值存储在key 中。

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)

从多映射中移除由迭代器pos 所指向的 (键, 值) 对，并返回指向该映射中下一个元素的迭代器。

另请参阅 remove()。

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

从多映射中移除由迭代器范围 [first,last) 所指向的 (键, 值) 对。返回一个迭代器，该迭代器指向多映射中紧随最后一个被移除元素之后的项。

该函数在 Qt 6.0 中引入。

另请参阅 remove()。

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

返回一个迭代器，该迭代器指向多映射中键为key 的项。

如果多映射中不存在键为key 的项，则该函数返回end()。

如果多映射中包含多个键为key 的项，则该函数返回一个指向最近插入的值的迭代器。通过递增迭代器可以访问其他值。例如，以下代码演示了如何遍历所有具有相同键的项：

auto i = multimap.find("plenty");
while (i != multimap.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

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

如果映射中不存在此类项，则该函数返回 `end()`。

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

T &QMultiMap::first()

返回多映射中第一个值的引用，即映射到最小键的值。该函数假设多映射不为空。

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

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

const T &QMultiMap::first() const

const Key &QMultiMap::firstKey() const

返回多映射中最小键的引用。该函数假设多映射不为空。

该函数的执行时间为常数时间。

另请参阅 lastKey()、first()、keyBegin() 以及isEmpty()。

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

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

如果映射中已经存在键为replace 的项，该函数将直接创建一个新的项。（此行为与 ()不同，后者会覆盖现有项的值。）

QMultiMap 允许重复键，并按键值升序存储项目。对于重复键，其值将按反向插入顺序存储（最近插入的值排在最前面）。

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

另请参阅 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 风格迭代器。

另请参阅 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 风格的const迭代器。

另请参阅 keyValueBegin()。

QList<Key> QMultiMap::keys() const

返回一个列表，其中包含多映射中所有键，并按升序排列。如果在多映射中某个键出现多次，则该键在列表中也会出现多次。

该排序顺序保证与values()所使用的排序顺序一致。

该函数以线性时间复杂度创建一个新列表。通过将keyBegin() 转换为keyEnd() 进行迭代，可以避免由此产生的时间和内存开销。

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

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

返回一个列表，其中包含与值value 关联的所有键，按升序排列。

该函数可能运行较慢（线性时间），因为QMultiMap 的内部数据结构是为按键快速查找而优化的，而非按值查找。

T &QMultiMap::last()

返回多映射中最后一个值的引用，即映射到最大键的值。该函数假设该映射不为空。

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

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

const T &QMultiMap::last() const

const Key &QMultiMap::lastKey() const

返回多映射中最大键的引用。该函数假设多映射不为空。

该函数的执行时间为常数时间。

另请参阅 firstKey()、last()、keyEnd() 以及isEmpty()。

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

返回一个迭代器，该迭代器指向映射中键为key 的第一个项。如果映射中不存在键为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 的最后一个项之后的下一个项。如果映射中不存在键为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 关联的值。

如果多值映射中不存在键为key 的项，则该函数返回defaultValue 。如果未指定defaultValue ，则该函数返回一个默认构造的值。如果多值映射中存在多个key 的项，则返回最近插入的那一个的值。

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

QList<T> QMultiMap::values() const

返回一个列表，其中包含映射中的所有值，按键的升序排列。如果一个键关联了多个值，则该键的所有值都会包含在列表中，而不仅仅是最近插入的那个。

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

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

返回一个列表，其中包含与键key 关联的所有值，按从最新插入到最旧插入的顺序排列。

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

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

将other 通过move赋值给此QMultiMap 实例。

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

将other 赋值给此多映射，并返回对此多映射的引用。