QMap Class

成员函数文档

[default] 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()。

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

构建other 的副本。

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

另请参阅 operator= 。

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

通过 move 构造一个 QMap 实例。

[implicit] QMap::~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<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

返回一个指向 map 中第一个元素的 constSTL 风格迭代器。

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

如果映射中不存在键为 `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 风格的const迭代器。

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

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

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

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 的键；如果映射中不存在值为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

返回一个指向映射中最后一个键之后的虚拟项的 constSTL 风格迭代器。

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

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

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

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

const T &QMap::last() const

const Key &QMap::lastKey() const

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

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

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

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

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

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

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

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

将此地图与other 互换。该操作非常快速，且绝不会失败。

T QMap::take(const Key &key)

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

如果该项在映射中不存在，则该函数仅返回一个通过默认构造创建的值。

如果您不使用返回值，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 的最后一个项之后的紧邻项。如果映射中不存在键为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()。

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

将other 通过Move-assigns操作赋值给此QMap 实例。

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

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

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

返回与键key 关联的值，该值以可修改引用形式返回。

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

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

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

与value()相同。