QMap类

成员函数文档

返回一个范围对象，允许作为键/值对迭代此映射。例如，此范围对象可以用在基于范围的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（）。

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

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

[显式构造] QMap::QMap(const std::map<Key, T> &other)

构建other的副本。

另请参阅toStdMap().

[显式构造] QMap::QMap(std::map<Key, T> &&other)

通过移动从other构造一个映射。

另请参阅toStdMap().

[默认 " QMap::QMap(const QMap<Key, T> &other)

构建other的副本。

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

另请参阅operator=.

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

移动构造QMap实例。

[默认] 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

返回一个指向键 key 在该映射中项的常量迭代器。

如果映射不包含具有键 key 的项，则该函数返回 constEnd。

另请参阅find。

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

返回一个指向映射中第一个条目的常量 STL-style iterator。

另请参阅keyValueBegin。

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

返回一个指向映射中最后一个条目的虚拟条目的常量 STL-style iterator。

另请参阅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-style iterator。

另请参阅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)

返回一对迭代器，用于界定在key下存储的值的范围 [first, second)。

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)

从地图中删除由迭代器范围 [first, last) 指向的（键，值）对。返回指向删除元素之后地图中元素的迭代器。

此函数是在 Qt 6.0 中引入的。

另请参阅remove().

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

返回指向具有键 key 的地图项的迭代器。

如果地图中不包含键 key 的元素，则该函数返回 end(）。

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

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

这是一个重载函数。

T &QMap::first()

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

在调用（或const版本）时，该操作以 常数时间 执行。

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

const T &QMap::first() const

这是一个重载函数。

const Key &QMap::firstKey() const

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

此操作在常数时间内执行。

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

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)

这是一个重载函数。

在指定位置pos处插入具有键key和值value的新项。

如果使用constBegin()作为提示，则表示该key小于映射中的任何键，而constEnd()则表示该key大于映射中的任何键。否则，提示应满足条件 (pos - 1)。 key() < key <= pos.key().如果提示pos不正确，则将其忽略并执行常规插入。

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

如果提示正确且映射未共享，则插入操作在平均常数时间内执行。

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

注意：请小心使用提示。使用旧共享实例的迭代器可能会导致崩溃，同时也存在将映射和pos映射静默损坏的风险。

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

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

将map中的所有项目插入到当前映射中。

如果两个映射都存在键是通用的，其值将用map中存储的值替换。

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

将map中的所有项目移动到当前映射中。

如果两个映射都存在键是通用的，其值将用map中存储的值替换。

如果map是共享的，则将复制这些项目。

bool QMap::isEmpty() const

如果映射不包含任何项目，则返回true；否则返回false。

另请参阅size()。

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

这是一个重载函数。

返回值为 value 的第一个键，若地图中不含有值为 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-style iterator。

另请参阅keyValueEnd()。

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

返回一个指向地图中最后一个条目之后的虚拟条目的 STL风格的迭代器。

另请参阅keyValueBegin。

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

返回一个指向映射中最后一个条目的虚拟条目的常量 STL-style iterator。

另请参阅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中最后一个值的引用，即映射到最大键的值。此函数假设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)

返回一个指向map中第一个具有键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)

从map中删除所有具有键key的项。返回删除的项目数，如果键存在于map中，则为1，否则为0。

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

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

从map中删除所有使谓词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中(key, value)对的数量。

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

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

与此map交换map other。此操作非常快且从不失败。

T QMap::take(const Key &key)

从映射中移除键为 key 的项目，并返回与其关联的值。

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

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

另请参阅remove().

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

返回一个与该 QMap 相等的 STL 映射。

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

这是一个重载函数。

此函数是在 Qt 6.0 中引入的。

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

返回一个指向映射中键为 key 的最后一个项目的下一个项的迭代器。如果映射中不包含键为 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

返回一个包含映射中所有值的列表，按键的升序排列。

此函数以 线性时间 创建一个新列表。通过从 keyValueBegin() 迭代到 keyValueEnd()，可以避免涉及的时间和内存使用。

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

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

将 other 赋予此映射，并返回对此映射的引用。

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

将other移动赋值到本QMap实例。

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

返回与键key关联的值的可修改引用。

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

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

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

这是一个重载函数。

等同于 value()。