QMap Class

成员函数文档

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

QMap<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 。

QMap::QMap()

构造一个空地图。

另请参见 clear().

[explicit] QMap::QMap(const std::map<Key, T> &other)

构造other 的副本。

另请参见 toStdMap().

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

用初始化列表list 中每个元素的副本构建一个映射。

[explicit] QMap::QMap(std::map<Key, T> &&other)

通过移动other 构建地图。

另请参见 toStdMap().

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

构造other 的副本。

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

另请参见 operator= 。

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

Move- 构造一个 QMap 实例。

[default] QMap::~QMap()

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

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

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

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

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

这是一个重载函数。

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

返回指向地图中第一个项目的STL 样式迭代器。

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

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

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

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

void QMap::clear()

删除地图上的所有项目。

另请参阅 remove().

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

返回指向地图中第一个项目的STL 样式迭代器。

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

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

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

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

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

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

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

另请参见 find()。

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

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

另请参见 keyValueBegin()。

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

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

另请参见 constKeyValueBegin().

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

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

另请参阅 count() 。

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

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

另请参阅 contains() 。

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

这是一个重载函数。

与size() 相同。

bool QMap::empty() const

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

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

返回一个STL 样式的迭代器，指向地图中最后一项之后的虚项。

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

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

这是一个重载函数。

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

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

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

这是一个重载函数。

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

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

另请参阅 remove().

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

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

此函数在 Qt 6.0 中引入。

另请参阅 remove() 。

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

返回指向 map 中键值为key 的项的迭代器。

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

另请参阅 constFind(),value(),values(),lowerBound() 和upperBound().

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

这是一个重载函数。

T &QMap::first()

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

当未共享（或调用 const 版本）时，执行时间不变。

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

const T &QMap::first() const

这是一个重载函数。

const Key &QMap::firstKey() const

返回 map 中最小键的引用。该函数假定 map 不为空。

执行时间不变。

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

void QMap::insert(QMap<Key, T> &&map)

将map 中的所有项目移入此地图。

如果两个地图共用一个键，则其值将替换为map 中存储的值。

如果map 是共享的，那么项目将被复制。

void QMap::insert(const QMap<Key, T> &map)

将map 中的所有项目插入该地图。

如果两个地图的键值相同，则其值将替换为map 中存储的值。

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

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

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

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

QMap<Key, T>::iterator QMap::insert(QMap<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 是错误的，则会被忽略，并执行常规插入操作。

如果已经存在键为key 的项目，则该项目值将被替换为value 。

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

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

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

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

bool QMap::isEmpty() const

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

另请参阅 size().

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

这是一个重载函数。

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

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

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

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

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

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

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

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

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

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

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

另请参见 keyValueEnd()。

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

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

另请参见 keyValueEnd()。

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

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

另请参见 keyValueBegin().

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

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

另请参见 keyValueBegin().

QList<Key> QMap::keys() const

以升序返回包含映射表中所有键的列表。

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

该函数以线性时间创建一个新列表。可以通过从keyBegin() 到keyEnd() 的迭代来避免所耗费的时间和内存。

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

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

这是一个重载函数。

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

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

T &QMap::last()

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

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

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

const T &QMap::last() const

这是一个重载函数。

const Key &QMap::lastKey() const

返回 map 中最大键的引用。此函数假定 map 不为空。

执行时间为对数。

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

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

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

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

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

这是一个重载函数。

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

从地图中删除关键字为key 的所有项目。如果键存在于地图中，则返回移除的条目数为 1，否则为 0。

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

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

从地图中删除谓词pred 返回 true 的所有元素。

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

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

此函数在 Qt 6.1 中引入。

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

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

返回 map 中（键、值）对的数量。

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

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

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

T QMap::take(const Key &key)

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

如果该项目不存在于 map 中，函数将简单地返回一个默认构造值。

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

另请参见 remove()。

std::map<Key, T> QMap::toStdMap() const &

返回等同于此QMap 的 STL 映射。

[since 6.0] std::map<Key, T> QMap::toStdMap() &&

这是一个重载函数。

此函数在 Qt 6.0 中引入。

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

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

示例

QMap<int, QString> map;
map.insert(1, "one");
map.insert(5, "five");
map.insert(10, "ten");

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

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

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

这是一个重载函数。

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

返回与键key 相关的值。

如果映射表中不包含键为key 的项，函数将返回defaultValue 。如果未指定defaultValue ，函数将返回默认构造值。

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

QList<T> QMap::values() const

按键的升序返回一个包含 map 中所有值的列表。

该函数以线性时间创建一个新列表。可以通过从keyValueBegin() 到keyValueEnd() 的迭代来避免耗费时间和内存。

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

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

Move-assignsother 到此QMap 实例。

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

为该地图指定other ，并返回对该地图的引用。

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

以可修改引用的形式返回与 keykey 相关联的值。

如果映射表中不包含键值为key 的项目，则函数会在映射表中插入一个默认构造的键值为 key 的值，并返回该值的引用。

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

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

这是一个重载函数。

与value() 相同。