QHash类

成员函数文档

这是一个重载函数。

返回与key关联的值。

如果哈希表中没有与key关联的项，则函数返回defaultValue，或者如果没有提供此参数，则返回一个默认构造的值。

返回映射到value的第一个键。如果哈希表中没有映射到value的项，则返回defaultKey，或者如果没有提供此参数，则返回一个默认构造的键。

此函数可能很慢（线性时间），因为QHash的内部数据结构是针对快速通过键查找进行优化的，而不是通过值。

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

QHash<QString, int> hash;
hash.insert("January", 1);
hash.insert("February", 2);
// ...
hash.insert("December", 12);

for (auto [key, value] : hash.asKeyValueRange()) {
    cout << qPrintable(key) << ": " << value << endl;
    --value; // convert to JS month indexing
}

请注意，以这种方式获取的键和值都是对哈希表中相应键和值的引用。特别是，修改值将修改哈希本身。

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

另请参阅QKeyValueIterator。

向容器插入一个新元素。该新元素使用 args 作为构造参数就地构造。

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

[noexcept] QHash::QHash()

构造一个空散列表。

另请参阅 clear().

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

使用初始化列表 list 中每个元素的一个副本来构造散列表。

模板 InputIterator<typename InputIterator> QHash::QHash(InputIterator begin, InputIterator end)

使用迭代器范围 [begin, end) 中每个元素的一个副本来构造散列表。该范围中迭代的元素必须是具有 first 和 second 数据成员（如 std::pair），可转换为 Key 和可转换为 T 的对象；或者迭代器必须具有 key() 和 value() 成员函数，分别返回可转换为 Key 和可转换为 T 的键和值。

[noexcept] QHash::QHash(const QHash::Key, T> &other)

构造其他的一个副本。

由于 QHash 是 隐式共享 的，并且此操作发生在 常数时间 内，这使得从函数中返回 QHash 非常快。如果共享实例被修改，则将其复制（写时复制），这需要 线性时间。

另请参阅 operator=().

[noexcept] QHash::QHash(QHash::Key, T> &&other)

移动构造一个 QHash 实例，使其指向与 other 相同的对象。

QHash::~QHash()

销毁散列表。对散列中值的引用以及该散列的所有迭代器都变为无效。

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

返回指向散列表中第一个项目的 STL 样式迭代器。

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

[noexcept] QHash<Key, T>::const_iterator QHash::begin() const

这是一个重载函数。

[noexcept] qsizetype QHash::capacity() const

返回 QHash 的内部散列表中的桶的数量。

该函数的惟一目的是提供调整QHash内存使用的方法。一般来说，您很少需要调用此函数。如果想知道哈希中包含多少项，请调用size()。

另请参阅reserve()和squeeze()。

[noexcept] QHash<Key, T>::const_iterator QHash::cbegin() const

返回一个指向哈希中第一个项目的常量STL-style迭代器。

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

[noexcept] QHash<Key, T>::const_iterator QHash::cend() const

返回一个指向哈希中最后一个项目之后虚拟项目的常量STL-style迭代器。

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

[noexcept(...)] void QHash::clear()

从哈希中删除所有项目并释放它使用的所有内存。

另请参阅remove()。

[noexcept] QHash<Key, T>::const_iterator QHash::constBegin() const

返回一个指向哈希中第一个项目的常量STL-style迭代器。

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

[noexcept] QHash<Key, T>::const_iterator QHash::constEnd() const

返回一个指向哈希中最后一个项目之后虚拟项目的常量STL-style迭代器。

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

[noexcept] QHash<Key, T>::const_iterator QHash::constFind(const Key &key) const

返回一个指向哈希中具有key的项目的迭代器。

如果哈希中没有具有key的项目，则函数返回constEnd。

另请参阅find()。

[noexcept] QHash<Key, T>::const_key_value_iterator QHash::constKeyValueBegin() const

返回一个指向哈希中第一个条目的常量STL-style迭代器。

另请参阅keyValueBegin()。

[noexcept] QHash<Key, T>::const_key_value_iterator QHash::constKeyValueEnd() const

返回一个指向哈希中最后一个条目之后虚拟条目的常量STL-style迭代器。

另请参阅constKeyValueBegin()。

[noexcept] bool QHash::contains(const Key &key) const

如果哈希表包含具有 key 的项，则返回 true；否则返回 false。

另请参阅count()。

[noexcept] qsizetype QHash::count(const Key &key) const

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

另请参阅contains()。

[noexcept] qsizetype QHash::count() const

这是一个重载函数。

与 size() 相同。

[noexcept] bool QHash::empty() const

此函数是为 STL 兼容性提供的。它与 isEmpty() 相等，如果哈希表为空则返回 true，否则返回 false。

[noexcept] QHash<Key, T>::iterator QHash::end()

返回一个指向哈希表中最后一个项后面的虚拟项的 STL 风格迭代器。

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

[noexcept] QHash<Key, T>::const_iterator QHash::end() const

这是一个重载函数。

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

从哈希表中移除与迭代器 pos 关联的 (key, value) 对，并返回指向哈希表中下一个项的迭代器。

此函数永远不会导致 QHash 重新散列其内部数据结构。这意味着可以在迭代时安全地调用它，而不会影响哈希表中项的顺序。例如

QHash<QObject *, int> objectHash;
...
QHash<QObject *, int>::iterator i = objectHash.find(obj);
while (i != objectHash.end() && i.key() == obj) {
    if (i.value() == 0) {
        i = objectHash.erase(i);
    } else {
        ++i;
    }
}

另请参阅remove()、take() 和 find()。

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

返回一个指向哈希中具有key的项目的迭代器。

如果哈希表中没有与 key 相关的项，则该函数返回 end()。

如果哈希表中有多个具有 key 的项，则此函数返回一个指向最近插入的值的迭代器。其他值可以通过递增迭代器访问。例如，下面是一些遍历具有相同键的所有项的代码示例

QHash<QString, int> hash;
...
QHash<QString, int>::const_iterator i = hash.find("HDR");
while (i != hash.end() && i.key() == "HDR") {
    cout << i.value() << endl;
    ++i;
}

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

[noexcept] QHash<Key, T>::const_iterator QHash::find(const Key &key) const

这是一个重载函数。

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

使用 键 和值为 value 添加新项。

如果已存在具有 键 的项，则该项的值将用 value 替换。

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

void QHash::insert(const QHash<Key, T> &other)

将 other 中所有项插入到该哈希中。

如果键在两个哈希中都有，则其值将用 other 中存储的值替换。

[noexcept] bool QHash::isEmpty() const

若哈希中不包含任何项，则返回 true；否则返回 false。

另请参阅size。

[noexcept] QHash<Key, T>::key_iterator QHash::keyBegin() const

返回一个指向哈希中第一个键的常量 STL-style 迭代器。

另请参阅keyEnd。

[noexcept] QHash<Key, T>::key_iterator QHash::keyEnd() const

返回一个指向哈希中最后一个键之后的假设项目的常量 STL-style 迭代器。

另请参阅keyBegin。

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

返回指向哈希中第一个条目的 STL-style 迭代器。

另请参阅keyValueEnd。

[noexcept] QHash<Key, T>::const_key_value_iterator QHash::keyValueBegin() const

返回一个指向哈希中第一个条目的常量STL-style迭代器。

另请参阅keyValueEnd。

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

返回指向哈希中最后一个条目之后的假设条目的 STL-style 迭代器。

另请参阅keyValueBegin()。

[noexcept] QHash<Key, T>::const_key_value_iterator QHash::keyValueEnd() const

返回一个指向哈希中最后一个条目之后虚拟条目的常量STL-style迭代器。

另请参阅keyValueBegin()。

QList<Key> QHash::keys() const

返回一个包含哈希中所有键的列表，顺序任意。

顺序 guaranteed to 与 values() 中使用的顺序相同。

此函数以线性时间创建新列表。可以通过从 keyBegin() 迭代到 keyEnd() 来避免因此而产生的时空消耗。

另请参阅values() 和 key。

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

这是一个重载函数。

返回一个包含与值 value 相关的所有键的列表，顺序任意。

此函数可能很慢（线性时间），因为QHash的内部数据结构是针对快速通过键查找进行优化的，而不是通过值。

[noexcept] float QHash::load_factor() const

返回 QHash 内部哈希表当前的负载因子。这与 capacity()/size(). 相同。使用的实现将努力将负载因子保持在 0.25 到 0.5 之间。这样可以避免过多的哈希表冲突，从而降低性能。

即使在负载因子较低的情况下，哈希表的实现也有非常低的内存开销。

此方法仅出于诊断目的，您很少需要自己调用它。

另请参阅reserve()和squeeze()。

bool QHash::remove(const Key &key)

从哈希表中移除具有 key 的项目。如果键存在于哈希表中并且已经移除，则返回 true，否则返回 false。

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

[since 6.1] template <typename Predicate> qsizetype QHash::removeIf(Predicate pred)

从哈希表中移除所有使谓词 pred 返回 true 的元素。

该函数支持接收参数为 QHash<Key, T>::iterator 或 std::pair<const Key &, T &> 类型的谓词。

如果移除了元素，则返回移除的元素数量。

此功能是自 Qt 6.1 引入的。

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

void QHash::reserve(qsizetype size)

确保 QHash 的内部哈希表有足够的空间存储至少 size 项，而无需扩展哈希表。

这意味着哈希表将包含至少 2 * size 个桶，以确保良好的性能。

此函数对于需要构建大型哈希表且希望避免重复分配的代码很有用。例如

QHash<QString, int> hash;
hash.reserve(20000);
for (int i = 0; i < 20000; ++i)
    hash.insert(keys[i], values[i]);

理想情况下，size 应该是哈希表中预期项目的最大数量。然后 QHash 将选择允许在表中存储 size 项的最小桶数。如果 size 是低估的，最坏的情况是 QHash 将变得稍微慢一些。

通常情况下，您很少需要调用此函数。 QHash 的内部哈希表会自动扩展以提供良好的性能而不浪费太多内存。

另请参阅squeeze() 和 capacity().

[noexcept] qsizetype QHash::size() const

返回哈希表中的项目数量。

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

void QHash::squeeze()

将 QHash 内部哈希表的大小减少以节省内存。

此函数的唯一目的是提供一种调整 QHash 内存使用的方式。通常，您很少需要调用此函数。

另请参阅reserve() 和 capacity。

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

交换此哈希与其它哈希 other。此操作非常快且永远不会失败。

T QHash::take(const Key &key)

从哈希中删除具有 key 的项并返回与其关联的值。

如果项不在哈希中，则函数仅返回一个 默认构造的值。

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

另请参阅remove()。

QList<T> QHash::values() const

返回包含哈希中所有值的列表，顺序任意。

顺序保证与 keys() 使用的一致。

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

另请参阅keys() 和 value。

bool QHash::operator!=(const QHash<Key, T> &other) const

如果 other 不等于此哈希，则返回 true；否则返回 false。

如果两个哈希包含相同的（键，值）对，则认为它们是相等的。

此函数要求值类型实现 operator==()。

另请参阅operator==。

[noexcept(...)] QHash<Key, T> &QHash::operator=(const QHash<Key, T> &other)

将 other 赋值给此哈希并返回对此哈希的引用。

[noexcept] QHash<Key, T> &QHash::operator=(QHash<Key, T> &&other)

移动赋值 other 到此 QHash 实例。

bool QHash::operator==(const QHash<Key, T> &other) const

如果 other 等于此哈希，则返回 true；否则返回 false。

如果两个哈希包含相同的（键，值）对，则认为它们是相等的。

此函数要求值类型实现 operator==()。

另请参阅operator!=。

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

返回与 key 关联的值，作为一个可修改的引用。

如果哈希中不包含具有 key 的项目，则函数会将默认构造的值插入到哈希表中，并将该值与 key 关联，并返回对该值的引用。

也见 insert() 和 value。

[noexcept] const T QHash::operator[](const Key &key) const

这是一个重载函数。

与 value 相同。