Spec-Zone.ru › Qt 6.0

Класс QHash

шаблон <typename Key, typename T> класс QHash

Класс QHash — это шаблонный класс, предоставляющий словарь на основе хеш-таблицы. Подробнее...

Заголовок: #include <QHash>
CMake: find_package(Qt6 COMPONENTS Core REQUIRED) target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
  • Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются повторно входящими.

Публичные типы

класс const_iterator
класс iterator
класс key_iterator
ConstIterator
Iterator
const_key_value_iterator
difference_type
key_type
key_value_iterator
mapped_type
size_type

Публичные функции

QHash(InputIterator begin, InputIterator end)
QHash(QHash<Key, T> &&other)
QHash(const QHash<Key, T> &other)
QHash(std::initializer_list<std::pair<Key, T> > list)
QHash()
QHash<Key, T> & operator=(QHash<Key, T> &&other)
QHash<Key, T> & operator=(const QHash<Key, T> &other)
~QHash()
QHash::iterator begin()
QHash::const_iterator begin() const
qsizetype capacity() const
QHash::const_iterator cbegin() const
QHash::const_iterator cend() const
void clear()
QHash::const_iterator constBegin() const
QHash::const_iterator constEnd() const
QHash::const_iterator constFind(const Key &key) const
QHash::const_key_value_iterator constKeyValueBegin() const
QHash::const_key_value_iterator constKeyValueEnd() const
bool contains(const Key &key) const
qsizetype count(const Key &key) const
qsizetype count() const
QHash::iterator emplace(const Key &key, Args &&... args)
QHash::iterator emplace(Key &&key, Args &&... args)
bool empty() const
QHash::iterator end()
QHash::const_iterator end() const
QHash::iterator erase(QHash::const_iterator pos)
QHash::iterator find(const Key &key)
QHash::const_iterator find(const Key &key) const
QHash::iterator insert(const Key &key, const T &value)
void insert(const QHash<Key, T> &other)
bool isEmpty() const
Key key(const T &value, const Key &defaultKey = Key()) const
QHash::key_iterator keyBegin() const
QHash::key_iterator keyEnd() const
QHash::key_value_iterator keyValueBegin()
QHash::const_key_value_iterator keyValueBegin() const
QHash::key_value_iterator keyValueEnd()
QHash::const_key_value_iterator keyValueEnd() const
QList<Key> keys() const
QList<Key> keys(const T &value) const
float load_factor() const
bool remove(const Key &key)
void reserve(qsizetype size)
qsizetype size() const
void squeeze()
void swap(QHash<Key, T> &other)
T take(const Key &key)
T value(const Key &key, const T &defaultValue = T()) const
QList<T> values() const
QTypeTraits::compare_eq_result<U> operator!=(const QHash<Key, T> &other) const
QTypeTraits::compare_eq_result<U> operator==(const QHash<Key, T> &other) const
T & operator[](const Key &key)
const T operator[](const Key &key) const

Связанные нечленные функции

int qGlobalQHashSeed()
size_t qHash(const QSslDiffieHellmanParameters &dhparam, size_t seed)
size_t qHash(const QStringRef &key, size_t seed)
size_t qHash(const QUrl &url, size_t seed = 0)
size_t qHash(const QOcspResponse &response, size_t seed)
size_t qHash(const QString &key, size_t seed = 0)
size_t qHash(char key, size_t seed = 0)
size_t qHash(const QDateTime &key, size_t seed = 0)
size_t qHash(QSslEllipticCurve curve, size_t seed)
size_t qHash(const QSet<T> &key, size_t seed = 0)
size_t qHash(const QHash<Key, T> &key, size_t seed = 0)
size_t qHash(const QBitArray &key, size_t seed = 0)
size_t qHash(uchar key, size_t seed = 0)
size_t qHash(QDate key, size_t seed = 0)
size_t qHash(QLatin1String key, size_t seed = 0)
size_t qHash(signed char key, size_t seed = 0)
size_t qHash(QTime key, size_t seed = 0)
size_t qHash(ushort key, size_t seed = 0)
size_t qHash(short key, size_t seed = 0)
size_t qHash(uint key, size_t seed = 0)
size_t qHash(const std::pair<T1, T2> &key, size_t seed = 0)
size_t qHash(const QVersionNumber &key, size_t seed = 0)
size_t qHash(int key, size_t seed = 0)
size_t qHash(const QTypeRevision &key, size_t seed = 0)
size_t qHash(ulong key, size_t seed = 0)
size_t qHash(QPoint key, size_t seed = 0)
size_t qHash(long key, size_t seed = 0)
size_t qHash(quint64 key, size_t seed = 0)
size_t qHash(qint64 key, size_t seed = 0)
size_t qHash(float key, size_t seed = 0)
size_t qHash(double key, size_t seed = 0)
size_t qHash(long double key, size_t seed = 0)
size_t qHash(wchar_t key, size_t seed = 0)
size_t qHash(char16_t key, size_t seed = 0)
size_t qHash(char32_t key, size_t seed = 0)
size_t qHash(char8_t key, size_t seed = 0)
size_t qHash(const T *key, size_t seed = 0)
size_t qHash(std::nullptr_t key, size_t seed = 0)
size_t qHash(const QChar key, size_t seed = 0)
size_t qHash(const QByteArray &key, size_t seed = 0)
size_t qHash(const QByteArrayView &key, size_t seed = 0)
size_t qHashBits(const void *p, size_t len, size_t seed = 0)
size_t qHashMulti(size_t seed, const T &... args)
size_t qHashMultiCommutative(size_t seed, const T &... args)
size_t qHashRange(InputIterator first, InputIterator last, size_t seed = 0)
size_t qHashRangeCommutative(InputIterator first, InputIterator last, size_t seed = 0)
void qSetGlobalQHashSeed(int newSeed)
QDataStreamIfHasOStreamOperators<Key, T> operator<<(QDataStream &out, const QHash<Key, T> &hash)
QDataStreamIfHasIStreamOperators<Key, T> operator>>(QDataStream &in, QHash<Key, T> &hash)

Подробное описание

QHash<Key, T> — один из универсальных классов контейнеров Qt. Он хранит пары (ключ, значение) и обеспечивает очень быстрый поиск значения, соответствующего ключу.

QHash предоставляет функциональность, очень похожую на QMap. Различия заключаются в следующем:

  • QHash обеспечивает более быстрый поиск, чем QMap. (См. Вычислительная сложность для получения подробной информации.)
  • При итерировании по QMap элементы всегда отсортированы по ключу. В QHash элементы упорядочены произвольным образом.
  • Тип ключа в QMap должен поддерживать оператор <(). Тип ключа в QHash должен поддерживать оператор ==() и глобальную функцию хеширования, называемую qHash() (см. qHash).

Вот пример QHash с ключами типа QString и значениями типа int:

QHash<QString, int> hash;

Чтобы вставить пару (ключ, значение) в хеш-таблицу, можно использовать оператор []:

hash["one"] = 1;
hash["three"] = 3;
hash["seven"] = 7;

Это вставляет следующие три пары (ключ, значение) в QHash: ("one", 1), ("three", 3) и ("seven", 7). Другой способ вставки элементов в хеш-таблицу — использование метода insert():

hash.insert("twelve", 12);

Для поиска значения используйте оператор [] или метод value():

int num1 = hash["thirteen"];
int num2 = hash.value("thirteen");

Если в хеш-таблице нет элемента с заданным ключом, эти функции возвращают значение по умолчанию.

Если вы хотите проверить, содержит ли хэш определенный ключ, используйте contains():

int timeout = 30;
if (hash.contains("TIMEOUT"))
    timeout = hash.value("TIMEOUT");

Также есть перегрузка value(), которая использует второй аргумент в качестве значения по умолчанию, если нет элемента с указанным ключом:

int timeout = hash.value("TIMEOUT", 30);

В общем случае, рекомендуется использовать contains() и value() вместо оператора[]() для поиска ключа в хэше. Причина в том, что оператор[]() молча вставляет элемент в хэш, если элемент с таким же ключом не существует (если хэш не является константным). Например, следующий фрагмент кода создаст 1000 элементов в памяти:

// WRONG
QHash<int, QWidget *> hash;
...
for (int i = 0; i < 1000; ++i) {
    if (hash[i] == okButton)
        cout << "Found button at index " << i << Qt::endl;
}

Чтобы избежать этой проблемы, замените hash[i] на hash.value(i) в коде выше.

Внутри QHash используется хеш-таблица для выполнения поиска. Эта хеш-таблица автоматически увеличивается для обеспечения быстрого поиска без чрезмерного использования памяти. Вы всё ещё можете контролировать размер хеш-таблицы, вызвав reserve(), если вы уже примерно знаете, сколько элементов будет содержать QHash, но это не обязательно для получения хорошей производительности. Также можно вызвать capacity() для получения размера хеш-таблицы.

QHash не уменьшается автоматически, если элементы удаляются из таблицы. Чтобы минимизировать используемую память хэша, вызовите squeeze().

Если вы хотите просмотреть все пары (ключ, значение), хранящиеся в QHash, вы можете использовать итератор. QHash предоставляет как итераторы в стиле Java (QHashIterator и QMutableHashIterator), так и итераторы в стиле STL (QHash::const_iterator и QHash::iterator). Вот как итерировать по QHash<QString, int> с помощью итератора в стиле Java:

QHashIterator<QString, int> i(hash);
while (i.hasNext()) {
    i.next();
    cout << i.key() << ": " << i.value() << Qt::endl;
}

Вот тот же код, но с использованием итератора в стиле STL:

QHash<QString, int>::const_iterator i = hash.constBegin();
while (i != hash.constEnd()) {
    cout << i.key() << ": " << i.value() << Qt::endl;
    ++i;
}

QHash не упорядочен, поэтому последовательность итератора не может быть предсказуемой. Если требуется упорядочение по ключу, используйте QMap.

QHash допускает только одно значение на ключ. Если вы вызываете insert() с ключом, который уже существует в QHash, предыдущее значение удаляется. Например:

hash.insert("plenty", 100);
hash.insert("plenty", 2000);
// hash.value("plenty") == 2000

Если вам нужно хранить несколько записей для одного и того же ключа в хеш-таблице, используйте QMultiHash.

Если вам нужно только извлечь значения из хэша (а не ключи), вы также можете использовать foreach:

QHash<QString, int> hash;
...
foreach (int value, hash)
    cout << value << Qt::endl;

Элементы можно удалить из хэша несколькими способами. Один способ — вызвать remove(); это удалит любой элемент с заданным ключом. Другой способ — использовать QMutableHashIterator::remove(). Кроме того, вы можете очистить весь хэш с помощью clear().

Типы данных ключа и значения QHash должны быть присваиваемыми типами данных. Например, нельзя хранить QWidget в качестве значения; вместо этого храните QWidget *.

Функция хеширования qHash()

Тип ключа QHash имеет дополнительные требования, помимо того, что он является присваиваемым типом данных: он должен предоставлять оператор==(), и в пространстве имен типа также должна быть функция qHash(), возвращающая значение хэша для аргумента типа ключа.

Функция qHash() вычисляет числовое значение на основе ключа. Она может использовать любой алгоритм, лишь бы всегда возвращала одно и то же значение для одного и того же аргумента. Другими словами, если e1 == e2, то qHash(e1) == qHash(e2) должно выполняться и в этом случае. Однако, для получения хорошей производительности, функция qHash() должна по возможности стремиться возвращать разные значения хэша для разных ключей.

Для типа ключа K, функция qHash должна иметь одну из следующих подписей:

size_t qHash(K key);
size_t qHash(const K &key);

size_t qHash(K key, size_t seed);
size_t qHash(const K &key, size_t seed);

Перегрузки с двумя аргументами принимают целое без знака, которое должно быть использовано для инициализации расчёта функции хэширования. Это зерно предоставляется QHash для предотвращения атак на алгоритмическую сложность.algorithmic complexity attacks. Если определены перегрузки как с одним, так и с двумя аргументами для типа ключа, QHash использует последнюю (обратите внимание, что вы можете просто определить версию с двумя аргументами и использовать значение по умолчанию для параметра зерна).

Вот частичный список типов C++ и Qt, которые могут служить ключами в QHash: любой целочисленный тип (char, unsigned long и т. д.), любой указатель, QChar, QString и QByteArray. Для всех них заголовок <QHash> определяет функцию qHash() для вычисления подходящего значения хэша. Многие другие классы Qt также объявляют перегрузку qHash для своего типа; обратитесь к документации каждого класса.

Если вы хотите использовать другие типы в качестве ключа, убедитесь, что вы предоставили operator==() и реализацию qHash(). Функция qHashMulti() может быть использована для реализации qHash() для пользовательского типа, где обычно требуется получить значение хэша из нескольких полей:

Пример:

#ifndef EMPLOYEE_H
#define EMPLOYEE_H

class Employee
{
public:
    Employee() {}
    Employee(const QString &name, QDate dateOfBirth);
    ...

private:
    QString myName;
    QDate myDateOfBirth;
};

inline bool operator==(const Employee &e1, const Employee &e2)
{
    return e1.name() == e2.name()
           && e1.dateOfBirth() == e2.dateOfBirth();
}

inline size_t qHash(const Employee &key, size_t seed)
{
    return qHashMulti(seed, key.name(), key.dateOfBirth());
}

#endif // EMPLOYEE_H

В примере выше мы опирались на собственную реализацию Qt qHash() для QString и QDate, чтобы получить значение хэша для имени и даты рождения сотрудника соответственно.

Обратите внимание, что реализация перегрузок qHash(), предлагаемых Qt, может быть изменена в любое время. Вы не должны полагаться на то, что qHash() будет давать одинаковые результаты (для одинаковых входных данных) в разных версиях Qt.

Атаки на алгоритмическую сложность

Все хеш-таблицы уязвимы для определенного класса атак с отказом в обслуживании, в которых злоумышленник тщательно предварительно вычисляет набор различных ключей, которые будут хешироваться в одном ведре хеш-таблицы (или даже иметь одно и то же значение хэша). Цель атаки — получить худшее алгоритмическое поведение (O(n) вместо амортизированного O(1), см. Алгоритмическая сложность для получения подробностей) при вводе данных в таблицу.

Чтобы избежать такого худшего случая, вычисление значения хэша, выполняемое функцией qHash(), может быть «засолено» случайным зерном, что нейтрализует масштаб атаки. Это зерно автоматически генерируется QHash один раз на процесс и затем передаётся QHash в качестве второго аргумента перегрузки функции qHash() с двумя аргументами.

Эта случайность QHash включена по умолчанию. Хотя программы никогда не должны зависеть от определённого порядка QHash, могут быть ситуации, когда временно требуется детерминированное поведение, например, для отладки или тестирования регрессии. Чтобы отключить случайность, задайте переменной среды QT_HASH_SEED значение 0. Кроме того, вы можете вызвать функцию qSetGlobalQHashSeed() со значением 0.

См. также QHashIterator, QMutableHashIterator, QMap и QSet.

Документация по типам членов

QHash::ConstIterator

Синоним в стиле Qt для QHash::const_iterator.

QHash::Iterator

Синоним в стиле Qt для QHash::iterator.

[since 5.10] QHash::const_key_value_iterator

Тип QHash::const_key_value_iterator предоставляет итератор const в стиле STL для QHash.

QHash::const_key_value_iterator по существу такой же, как QHash::const_iterator с отличием, что оператор*() возвращает пару ключ/значение вместо значения.

Этот тип был введён в Qt 5.10.

См. также QKeyValueIterator.

[alias] QHash::difference_type

Тип для ptrdiff_t. Предоставлен для совместимости со STL.

[alias] QHash::key_type

Тип для Key. Предоставлен для совместимости со STL.

[since 5.10] QHash::key_value_iterator

Тип QHash::key_value_iterator предоставляет итератор в стиле STL для QHash.

QHash::key_value_iterator по существу такой же, как QHash::iterator с отличием, что оператор*() возвращает пару ключ/значение вместо значения.

Этот тип был введён в Qt 5.10.

См. также QKeyValueIterator.

[alias] QHash::mapped_type

Тип для T. Предоставлен для совместимости со STL.

[alias] QHash::size_type

Тип для int. Предоставлен для совместимости со STL.

Документация по функциям-членам

template <typename Args> QHash::iterator QHash::emplace(Key &&key, Args &&... args)

template <typename Args> QHash::iterator QHash::emplace(const Key &key, Args &&... args)

Вставляет новый элемент в контейнер. Новый элемент создаётся на месте с использованием args в качестве аргументов для его построения.

Возвращает итератор, указывающий на новый элемент.

[since 5.14] template <typename InputIterator> QHash::QHash(InputIterator begin, InputIterator end)

Создаёт хэш с копией каждого элемента в интервале итераторов [begin, end). Или элементы, перебираемые интервалом, должны быть объектами с first и second членами данных (например, QPair, std::pair, и т.д.), преобразуемыми в Key и соответственно в T; или итераторы должны иметь key() и value() функции-члены, возвращающие ключ, преобразуемый в Key и значение, преобразуемое в T соответственно.

Эта функция была введена в Qt 5.14.

[since 5.2] QHash::QHash(QHash<Key, T> &&other)

Создаёт экземпляр QHash, используя тот же объект, на который указывал other.

Эта функция была добавлена в Qt 5.2.

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

Создаёт копию other.

Эта операция выполняется за постоянное время, потому что QHash использует неявное совместное использование. Это делает возвращение QHash из функции очень быстрым. Если изменён общий экземпляр, он будет скопирован (копирование при записи), и это займёт линейное время.

См. также operator=().

[since 5.1] QHash::QHash(std::initializer_list<std::pair<Key, T> > list)

Создаёт хеш-таблицу с копией каждого элемента в списке инициализации list.

Эта функция была добавлена в Qt 5.1.

QHash::QHash()

Создаёт пустую хеш-таблицу.

См. также clear().

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

Перемещает other в этот экземпляр QHash.

Эта функция была добавлена в Qt 5.2.

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

Присваивает other этому хешу и возвращает ссылку на этот хеш.

QHash::~QHash()

Удаляет хеш-таблицу. Ссылки на значения в хеше и все итераторы этого хеша становятся недействительными.

QHash::iterator QHash::begin()

Возвращает итератор, указывающий на первый элемент в хеше.

См. также constBegin() и end().

QHash::const_iterator QHash::begin() const

Это перегруженная функция.

qsizetype QHash::capacity() const

Возвращает количество бакетов во внутренней хеш-таблице QHash.

Единственная цель этой функции — предоставить способ тонкой настройки использования памяти QHash. Как правило, вам редко придётся вызывать эту функцию. Если вы хотите узнать, сколько элементов в хеше, используйте size().

См. также reserve() и squeeze().

[since 5.0] QHash::const_iterator QHash::cbegin() const

Возвращает постоянный итератор, указывающий на первый элемент в хеше.

Эта функция была добавлена в Qt 5.0.

См. также begin() и cend().

[since 5.0] QHash::const_iterator QHash::cend() const

Возвращает постоянный итератор, указывающий на несуществующий элемент после последнего элемента в хеше.

Эта функция была добавлена в Qt 5.0.

См. также cbegin() и end().

void QHash::clear()

Удаляет все элементы из хеша и освобождает всю используемую им память.

См. также remove().

QHash::const_iterator QHash::constBegin() const

Возвращает постоянный итератор, указывающий на первый элемент в хеше.

См. также begin() и constEnd().

QHash::const_iterator QHash::constEnd() const

Возвращает постоянный итератор, указывающий на несуществующий элемент после последнего элемента в хеше.

См. также constBegin() и end().

QHash::const_iterator QHash::constFind(const Key &key) const

Возвращает итератор, указывающий на элемент с ключом в хеше.

Если в хеше нет элемента с ключом, функция возвращает constEnd().

См. также find().

[since 5.10] QHash::const_key_value_iterator QHash::constKeyValueBegin() const

Возвращает постоянный итератор, указывающий на первую пару «ключ-значение» в хеше.

Эта функция была добавлена в Qt 5.10.

См. также keyValueBegin().

[since 5.10] QHash::const_key_value_iterator QHash::constKeyValueEnd() const

Возвращает постоянный итератор, указывающий на несуществующий элемент после последней пары «ключ-значение» в хеше.

Эта функция была добавлена в Qt 5.10.

См. также constKeyValueBegin().

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

Возвращает true , если хеш содержит элемент с ключом; в противном случае возвращает false.

См. также count() и QMultiHash::contains().

qsizetype QHash::count(const Key &key) const

Возвращает количество элементов, связанных с ключом.

См. также contains().

qsizetype QHash::count() const

Это перегруженная функция.

То же самое, что size().

bool QHash::empty() const

Эта функция предоставляется для совместимости со STL. Она эквивалентна isEmpty(), возвращает true, если хеш пуст; в противном случае возвращает false.

QHash::iterator QHash::end()

Возвращает итератор, указывающий на несуществующий элемент после последнего элемента в хеше.

См. также begin() и constEnd().

QHash::const_iterator QHash::end() const

Это перегруженная функция.

[since 5.7] QHash::iterator QHash::erase(QHash::const_iterator pos)

Удаляет пару «ключ-значение», связанную с итератором pos из хеша и возвращает итератор следующего элемента в хеше.

Эта функция никогда не приводит к перехешированию внутренней структуры данных 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;
    }
}

Эта функция была добавлена в Qt 5.7.

См. также remove(), take() и find().

QHash::iterator QHash::find(const Key &key)

Возвращает итератор, указывающий на элемент с ключом в хеше.

Если в хеше нет элемента с ключом, функция возвращает end().

Если в хеше есть несколько элементов с ключом, эта функция возвращает итератор, который указывает на наиболее недавно вставленное значение. Другие значения доступны, увеличивая итератор. Например, вот код, который перебирает все элементы с одинаковым ключом:

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

См. также value() и values().

QHash::const_iterator QHash::find(const Key &key) const

Это перегруженная функция.

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

Вставляет новый элемент с ключом и значением value.

Если уже есть элемент с ключом, значение этого элемента заменяется на value.

[since 5.15] void QHash::insert(const QHash<Key, T> &other)

Вставляет все элементы хеша other в этот хеш.

Если ключ встречается в обоих хешах, его значение будет заменено значением, хранящимся в other.

END_OF_DOCUMENT_MARKER

Примечание: Если other содержит несколько записей с одним и тем же ключом, то конечное значение ключа является неопределённым.

Эта функция была введена в Qt 5.15.

bool QHash::isEmpty() const

Возвращает true если хэш не содержит элементов; в противном случае возвращает false.

См. также size().

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

Возвращает первый ключ, сопоставленный со значением value, или defaultKey, если в хэше нет элементов, сопоставленных со значением value.

Эта функция может быть медленной (линейное время), так как внутренняя структура данных QHash оптимизирована для быстрого поиска по ключу, а не по значению.

[since 5.6] QHash::key_iterator QHash::keyBegin() const

Возвращает константный итератор STL-стиля, указывающий на первый ключ в хэше.

Эта функция была введена в Qt 5.6.

См. также keyEnd().

[since 5.6] QHash::key_iterator QHash::keyEnd() const

Возвращает константный итератор STL-стиля, указывающий на воображаемый элемент после последнего ключа в хэше.

Эта функция была введена в Qt 5.6.

См. также keyBegin().

[since 5.10] QHash::key_value_iterator QHash::keyValueBegin()

Возвращает итератор STL-стиля, указывающий на первую запись в хэше.

Эта функция была введена в Qt 5.10.

См. также keyValueEnd().

[since 5.10] QHash::const_key_value_iterator QHash::keyValueBegin() const

Возвращает константный итератор STL-стиля, указывающий на первую запись в хэше.

Эта функция была введена в Qt 5.10.

См. также keyValueEnd().

[since 5.10] QHash::key_value_iterator QHash::keyValueEnd()

Возвращает итератор STL-стиля, указывающий на воображаемую запись после последней записи в хэше.

Эта функция была введена в Qt 5.10.

См. также keyValueBegin().

[since 5.10] QHash::const_key_value_iterator QHash::keyValueEnd() const

Возвращает константный итератор STL-стиля, указывающий на воображаемую запись после последней записи в хэше.

Эта функция была введена в Qt 5.10.

См. также keyValueBegin().

QList<Key> QHash::keys() const

Возвращает список, содержащий все ключи в хэше в произвольном порядке.

Порядок гарантированно совпадает с порядком, используемым функцией values().

Эта функция создаёт новый список за линейное время. Время и использование памяти, связанное с этим, можно избежать, итерируясь от keyBegin() до keyEnd().

См. также values() и key().

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

Это перегруженная функция.

Возвращает список, содержащий все ключи, связанные со значением value, в произвольном порядке.

Эта функция может быть медленной (линейное время), так как внутренняя структура данных QHash оптимизирована для быстрого поиска по ключу, а не по значению.

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

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

qsizetype QHash::size() const

Возвращает количество элементов в хэше.

См. также isEmpty() и count().

void QHash::squeeze()

Уменьшает размер внутренней таблицы хэширования QHash для экономии памяти.

Единственная цель этой функции — предоставить способ тонкой настройки использования памяти QHash. В общем случае вам крайне редко понадобится вызывать эту функцию.

См. также reserve() и capacity().

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

Меняет местами хэш other с этим хэшем. Эта операция очень быстрая и никогда не завершается неудачей.

T QHash::take(const Key &key)

Удаляет элемент с ключом key из хэша и возвращает связанное с ним значение.

Если элемент не существует в хэше, функция просто возвращает значение по умолчанию.

Если вам не нужно значение возврата, remove() более эффективен.

См. также remove().

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

Это перегруженная функция.

Возвращает значение, связанное с ключом key.

Если в хэше нет элемента с ключом key, функция возвращает defaultValue, которое является значением по умолчанию, если параметр не был указан.

QList<T> QHash::values() const

Возвращает список, содержащий все значения в хэше в произвольном порядке.

Порядок гарантированно совпадает с порядком, используемым функцией keys().

Эта функция создаёт новый список за линейное время. Время и использование памяти, связанное с этим, можно избежать, итерируясь от keyValueBegin() до keyValueEnd().

См. также keys() и value().

template <typename U> QTypeTraits::compare_eq_result<U> QHash::operator!=(const QHash<Key, T> &other) const

Возвращает true если other не равно этому хэшу; в противном случае возвращает false.

Два хэша считаются равными, если они содержат одинаковые пары (ключ, значение).

Эта функция требует, чтобы тип значения реализовывал operator==().

См. также operator==().

template <typename U> QTypeTraits::compare_eq_result<U> QHash::operator==(const QHash<Key, T> &other) const

Возвращает true если other равно этому хэшу; в противном случае возвращает false.

Два хэша считаются равными, если они содержат одинаковые пары (ключ, значение).

Эта функция требует, чтобы тип значения реализовывал operator==().

См. также operator!=().

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

Возвращает значение, связанное с ключом, в качестве изменяемой ссылки.

Если в хеш-таблице нет элемента с ключом, функция вставляет в хеш-таблицу элемент с ключом, содержащий значение по умолчанию, и возвращает ссылку на него.

См. также insert() и value().

const T QHash::operator[](const Key &ключ) const

Это перегруженная функция.

То же, что и value().

Связанные не члены

[since 5.6] int qGlobalQHashSeed()

Возвращает текущее глобальное зерно QHash.

Зерно устанавливается в любом вновь созданном QHash. См. qHash, чтобы узнать, как это зерно используется QHash.

Эта функция была добавлена в Qt 5.6.

См. также qSetGlobalQHashSeed.

[since 5.0] size_t qHash(const QUrl &url, size_t seed = 0)

Возвращает значение хэша для url. Если задано, seed используется для инициализации хэша.

Эта функция была добавлена в Qt 5.0.

[since 5.0] size_t qHash(const QString &key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.0] size_t qHash(char key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.0] size_t qHash(const QDateTime &key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.5] template <typename T> size_t qHash(const QSet<T> &key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Значение хэша не зависит от порядка элементов в key, то есть множества, содержащие одинаковые элементы, имеют одинаковое значение хэша.

Эта функция была добавлена в Qt 5.5.

[since 5.8] template <typename Key, typename T> size_t qHash(const QHash<Key, T> &key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Тип T должен поддерживаться qHash().

Эта функция была добавлена в Qt 5.8.

[since 5.0] size_t qHash(const QBitArray &key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.0] size_t qHash(uchar key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.0] size_t qHash(QDate key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.0] size_t qHash(QLatin1String key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.0] size_t qHash(signed char key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.0] size_t qHash(QTime key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.0] size_t qHash(ushort key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.0] size_t qHash(short key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.0] size_t qHash(uint key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.7] template <typename T1, typename T2> size_t qHash(const std::pair<T1, T2> &key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Типы T1 и T2 должны поддерживаться qHash().

Эта функция была добавлена в Qt 5.7.

[since 5.6] size_t qHash(const QVersionNumber &key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.6.

[since 5.0] size_t qHash(int key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 6.0] size_t qHash(const QTypeRevision &key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 6.0.

[since 5.0] size_t qHash(ulong key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 6.0] size_t qHash(QPoint key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 6.0.

[since 5.0] size_t qHash(long key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.0] size_t qHash(quint64 key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.0] size_t qHash(qint64 key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.0.

[since 5.3] size_t qHash(float key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.3.

[since 5.3] size_t qHash(double key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.3.

[since 5.3] size_t qHash(long double key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 5.3.

[since 6.0] size_t qHash(wchar_t key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для начального значения вычисления.

Эта функция была добавлена в Qt 6.0.

[since 6.0] size_t qHash(char16_t key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для инициализации вычисления.

Эта функция была представлена в Qt 6.0.

[since 6.0] size_t qHash(char32_t key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для инициализации вычисления.

Эта функция была представлена в Qt 6.0.

[since 6.0] size_t qHash(char8_t key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для инициализации вычисления.

Эта функция была представлена в Qt 6.0.

[since 5.0] template <typename T> size_t qHash(const T *key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для инициализации вычисления.

Эта функция была представлена в Qt 5.0.

[since 6.0] size_t qHash(std::nullptr_t key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для инициализации вычисления.

Эта функция была представлена в Qt 6.0.

[since 5.0] size_t qHash(const QChar key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для инициализации вычисления.

Эта функция была представлена в Qt 5.0.

[since 5.0] size_t qHash(const QByteArray &key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для инициализации вычисления.

Эта функция была представлена в Qt 5.0.

[since 6.0] size_t qHash(const QByteArrayView &key, size_t seed = 0)

Возвращает значение хэша для key, используя seed для инициализации вычисления.

Эта функция была представлена в Qt 6.0.

[since 5.4] size_t qHashBits(const void *p, size_t len, size_t seed = 0)

Возвращает значение хэша для блока памяти размером len, указанного p, используя seed для инициализации вычисления.

Используйте эту функцию только для реализации qHash() для собственных типов.

Например, вот как можно реализовать перегрузку qHash() для std::vector<int>:

inline size_t qHash(const std::vector<int> &key, size_t seed = 0)
{
    if (key.empty())
        return seed;
    else
        return qHashBits(&key.front(), key.size() * sizeof(int), seed);
}

Это использует тот факт, что std::vector размещает свои данные непрерывно. Если это не так, или содержащий тип имеет заполнение, используйте qHashRange() вместо этого.

Следует повторить, что реализация qHashBits() — как и перегрузки qHash(), предлагаемые Qt — может изменяться в любое время. Вы не должны полагаться на то, что qHashBits() будет давать одинаковые результаты (для одинаковых входных данных) в разных версиях Qt.

Эта функция была представлена в Qt 5.4.

См. также qHashRange() и qHashRangeCommutative().

[since 6.0] template <typename T> size_t qHashMulti(size_t seed, const T &... args)

Возвращает значение хэша для args, используя seed для инициализации вычисления, последовательно применяя qHash() к каждому элементу и объединяя значения хэшей в одно.

Обратите внимание, что порядок аргументов имеет значение. Если порядок не имеет значения, используйте qHashMultiCommutative() вместо этого. Если вы хэшируете сырую память, используйте qHashBits(); если хэшируете диапазон, используйте qHashRange().

Эта функция предоставляется для удобства реализации qHash() для собственных типов.

Например, вот как можно реализовать перегрузку qHash() для класса Employee:

#ifndef EMPLOYEE_H
#define EMPLOYEE_H

class Employee
{
public:
    Employee() {}
    Employee(const QString &name, QDate dateOfBirth);
    ...

private:
    QString myName;
    QDate myDateOfBirth;
};

inline bool operator==(const Employee &e1, const Employee &e2)
{
    return e1.name() == e2.name()
           && e1.dateOfBirth() == e2.dateOfBirth();
}

inline size_t qHash(const Employee &key, size_t seed)
{
    return qHashMulti(seed, key.name(), key.dateOfBirth());
}

#endif // EMPLOYEE_H

Эта функция была представлена в Qt 6.0.

См. также qHashMultiCommutative и qHashRange.

[since 6.0] template <typename T> size_t qHashMultiCommutative(size_t seed, const T &... args)

Возвращает значение хэша для args, используя seed для инициализации вычисления, последовательно применяя qHash() к каждому элементу и объединяя значения хэшей в одно.

Порядок аргументов несущественен. Если порядок имеет значение, используйте qHashMulti() вместо этого, так как это может привести к хэшированию лучшего качества. Если вы хэшируете сырую память, используйте qHashBits(); если хэшируете диапазон, используйте qHashRange().

Эта функция предоставляется для удобства реализации qHash() для собственных типов.

Эта функция была представлена в Qt 6.0.

См. также qHashMulti и qHashRange.

[since 5.5] template <typename InputIterator> size_t qHashRange(InputIterator first, InputIterator last, size_t seed = 0)

Возвращает значение хэша для диапазона [first,last), используя seed для инициализации вычисления, последовательно применяя qHash() к каждому элементу и объединяя значения хэшей в одно.

Возвращаемое значение этой функции зависит от порядка элементов в диапазоне. Это означает, что

{0, 1, 2}

и

{1, 2, 0}

хэшируются до разных значений. Если порядок не имеет значения, например, для хеш-таблиц, используйте qHashRangeCommutative() вместо этого. Если вы хэшируете сырую память, используйте qHashBits().

Используйте эту функцию только для реализации qHash() для собственных типов. Например, вот как можно реализовать перегрузку qHash() для std::vector<int>:

inline size_t qHash(const std::vector<int> &key, size_t seed = 0)
{
    return qHashRange(key.begin(), key.end(), seed);
}

Следует повторить, что реализация qHashRange() — как и перегрузки qHash(), предлагаемые Qt — может изменяться в любое время. Вы не должны полагаться на то, что qHashRange() будет давать одинаковые результаты (для одинаковых входных данных) в разных версиях Qt, даже если qHash() для типа элемента будет.

Эта функция была представлена в Qt 5.5.

См. также qHashBits() и qHashRangeCommutative().

[since 5.5] template <typename InputIterator> size_t qHashRangeCommutative(InputIterator first, InputIterator last, size_t seed = 0)

Возвращает значение хэша для диапазона [first,last), используя seed для инициализации вычисления, последовательно применяя qHash() к каждому элементу и объединяя значения хэшей в одно.

Возвращаемое значение этой функции не зависит от порядка элементов в диапазоне. Это означает, что

{0, 1, 2}

и

{1, 2, 0}

хэшируются до одинаковых значений. Если порядок имеет значение, например, для векторов и массивов, используйте qHashRange() вместо этого. Если вы хэшируете сырую память, используйте qHashBits().

Используйте эту функцию только для реализации qHash() для собственных типов. Например, вот как можно реализовать перегрузку qHash() для std::unordered_set<int>:

inline size_t qHash(const std::unordered_set<int> &key, size_t seed = 0)
{
    return qHashRangeCommutative(key.begin(), key.end(), seed);
}

Следует повторить, что реализация qHashRangeCommutative() — как и перегрузки qHash(), предлагаемые Qt — может изменяться в любое время. Вы не должны полагаться на то, что qHashRangeCommutative() будет давать одинаковые результаты (для одинаковых входных данных) в разных версиях Qt, даже если qHash() для типа элемента будет.

Эта функция была представлена в Qt 5.5.

См. также qHashBits() и qHashRange().

[since 5.6] void qSetGlobalQHashSeed(int newSeed)

Устанавливает глобальное зерно QHash в newSeed.

Ручное задание глобального значения зерна QHash следует выполнять только в целях тестирования и отладки, когда требуется детерминированное и воспроизводимое поведение в QHash. Мы не рекомендуем это делать в коде приложения, так как это может сделать ваше приложение уязвимым для атак на алгоритмическую сложность.

Начиная с Qt 5.10 и далее, разрешены только значения 0 и -1. Передача значения -1 переинициализирует глобальное зерно QHash случайным значением, а значение 0 используется для запроса стабильного алгоритма для типов C++ примитивов (например, int) и строковых типов (QString, QByteArray).

Зерно устанавливается в любом вновь созданном QHash. См. qHash о том, как это зерно используется QHash.

Если переменная среды QT_HASH_SEED установлена, вызов этой функции приведет к no-op.

Эта функция была представлена в Qt 5.6.

См. также qGlobalQHashSeed.

template <typename Key, typename T> QDataStreamIfHasOStreamOperators<Key, T> operator<<(QDataStream &out, const QHash<Key, T> &hash)

Записывает хеш hash в поток out.

Для этой функции типы ключа и значения должны реализовывать operator<<().

См. также Сериализация типов данных Qt.

template <typename Key, typename T> QDataStreamIfHasIStreamOperators<Key, T> operator>>(QDataStream &in, QHash<Key, T> &hash)

Читает хеш из потока in в hash.

Для этой функции типы ключа и значения должны реализовывать operator>>().

См. также Сериализация типов данных Qt.

© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/qt-6.0/qhash.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API