Класс QMap

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

• Список всех членов, включая унаследованные

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

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

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

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

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

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

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

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

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

QMap<QString, int> map;

Для вставки пары (ключ, значение) в карту можно использовать оператор[]():

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

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

map.insert("twelve", 12);

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

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

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

Чтобы проверить, содержит ли карта определённый ключ, используйте contains():

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

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

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

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

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

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

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

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

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

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

Элементы проходятся в порядке возрастания ключей.

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

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

Однако, для хранения нескольких значений на один ключ можно использовать QMultiMap. Если требуется извлечь все значения для одного ключа, можно использовать values(const Key &key), которая возвращает QList<T>:

QList<int> values = map.values("plenty");
for (int i = 0; i < values.size(); ++i)
    cout << values.at(i) << Qt::endl;

Другой подход — вызвать find(), чтобы получить итератор в стиле STL для первого элемента с ключом и итерироваться оттуда:

QMap<QString, int>::iterator i = map.find("plenty");
while (i != map.end() && i.key() == "plenty") {
    cout << i.value() << Qt::endl;
    ++i;
}

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

QMap<QString, int> map;
...
foreach (int value, map)
    cout << value << Qt::endl;

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

Типы данных ключа и значения QMap должны быть присваиваемыми типами данных. Это охватывает большинство типов данных, с которыми вы, вероятно, столкнётесь, но компилятор не позволит вам, например, хранить QWidget как значение; вместо этого храните указатель на QWidget *. Кроме того, тип ключа QMap должен предоставлять оператор <(). QMap использует его для сортировки элементов и предполагает, что два ключа x и y эквивалентны, если ни x < y ни y < x не истинно.

Пример:

#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)
{
    if (e1.name() != e2.name())
        return e1.name() < e2.name();
    return e1.dateOfBirth() < e2.dateOfBirth();
}

#endif // EMPLOYEE_H

В примере мы начинаем с сравнения имён сотрудников. Если они равны, мы сравниваем даты рождения, чтобы разрешить ничью.

См. также QMapIterator, QMutableMapIterator, QHash и QSet.

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

QMap::ConstIterator

Синоним в стиле Qt для QMap<Key, T>::const_iterator.

QMap::Iterator

Синоним в стиле Qt для QMap<Key, T>::iterator.

[since 5.10] QMap::const_key_value_iterator

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

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

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

См. также QKeyValueIterator.

[alias] QMap::difference_type

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

[alias] QMap::key_type

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

[since 5.10] QMap::key_value_iterator

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

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

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

См. также QKeyValueIterator.

[alias] QMap::mapped_type

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

[alias] QMap::size_type

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

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

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

Перемещающее создание экземпляра QMap.

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

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

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

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

См. также operator=.

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

Создаёт карту, перемещая данные из other.

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

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

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

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

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

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

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

QMap::QMap()

Создаёт пустую карту.

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

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

Перемещающее присваивание other текущему экземпляру QMap.

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

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

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

[default] QMap::~QMap()

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

QMap::iterator QMap::begin()

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

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

QMap::const_iterator QMap::begin() const

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

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

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

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

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

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

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

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

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

void QMap::clear()

Удаляет все элементы из отображения.

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

QMap::const_iterator QMap::constBegin() const

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

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

QMap::const_iterator QMap::constEnd() const

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

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

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

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

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

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

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

Возвращает постоянный итератор STL, указывающий на первую запись в отображении.

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

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

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

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

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

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

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

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

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

QMap::size_type QMap::count(const Key &key) const

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

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

QMap::size_type QMap::count() const

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

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

bool QMap::empty() const

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

QMap::iterator QMap::end()

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

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

QMap::const_iterator QMap::end() const

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

QPair<QMap::iterator, QMap::iterator> QMap::equal_range(const Key &key)

Возвращает пару итераторов, определяющих диапазон значений [first, second), которые хранятся по ключу key.

[since 5.6] QPair<QMap::const_iterator, QMap::const_iterator> QMap::equal_range(const Key &key) const

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

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

QMap::iterator QMap::erase(QMap::const_iterator pos)

Удаляет пару (ключ, значение), на которую указывает итератор pos, из отображения и возвращает итератор на следующий элемент в отображении.

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

[since 6.0] QMap::iterator QMap::erase(QMap::const_iterator first, QMap::const_iterator last)

Удаляет пары (ключ, значение), на которые указывают итераторы диапазона [first, last), из отображения. Возвращает итератор на элемент в отображении, следующий за последним удаленным элементом.

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

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

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

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

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

См. также constFind(), value(), values(), lowerBound(), и upperBound().

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

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

[since 5.2] T &QMap::first()

Возвращает ссылку на первое значение в отображении, то есть значение, сопоставленное с наименьшим ключом. Эта функция предполагает, что отображение не пусто.

При вызове несовместной (или const версии) эта функция выполняется за постоянное время.

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

См. также last(), firstKey(), и isEmpty().

[since 5.2] const T &QMap::first() const

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

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

[since 5.2] const Key &QMap::firstKey() const

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

Выполняется за постоянное время.

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

См. также lastKey(), first(), keyBegin(), и isEmpty().

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

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

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

См. также QMultiMap::insert().

[since 5.1] QMap::iterator QMap::insert(QMap::const_iterator pos, const Key &key, const T &value)

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

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

Если constBegin() используется в качестве подсказки, это указывает, что ключ меньше любого ключа в отображении, в то время как constEnd() предполагает, что ключ (строго) больше любого ключа в отображении. В противном случае подсказка должна удовлетворять условию (pos - 1).key() < ключ <= pos.key(). Если подсказка pos неверна, она игнорируется, и выполняется обычная вставка.

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

Если подсказка верна, а отображение не является общим, вставка выполняется за амортизированное постоянное время.

При создании отображения из отсортированных данных вставка наибольшего ключа первой с помощью constBegin() выполняется быстрее, чем вставка в отсортированном порядке с помощью constEnd(), так как constEnd() - 1 (которое необходимо для проверки правильности подсказки) требует логарифмического времени.

Примечание: Будьте осторожны с подсказкой. Предоставление итератора из более старой общей инстанции может привести к ошибке, но также существует риск, что это незаметно повредит как отображение, так и отображение pos.

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

См. также QMultiMap::insert().

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

Вставляет все элементы из map в это отображение.

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

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

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

См. также QMultiMap::insert().

[since 5.15] void QMap::insert(QMap<Key, T> &&map)

Перемещает все элементы из map в это отображение.

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

Если map является общим, то элементы будут скопированы вместо перемещения.

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

bool QMap::isEmpty() const

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

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

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

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

Возвращает первый ключ со значением value или defaultKey, если в отображении нет элемента со значением value. Если defaultKey не указан, функция возвращает ключ с значением по умолчанию.

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

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

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

Возвращает константный итератор в стиле STL, указывающий на первый ключ в отображении.

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

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

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

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

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

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

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

Возвращает итератор в стиле STL, указывающий на первую запись в отображении.

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

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

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

Возвращает константный итератор в стиле STL, указывающий на первую запись в отображении.

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

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

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

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

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

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

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

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

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

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

QList<Key> QMap::keys() const

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

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

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

См. также QMultiMap::uniqueKeys(), values() и key().

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

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

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

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

[since 5.2] T &QMap::last()

Возвращает ссылку на последнее значение в отображении, т.е. значение, сопоставленное с наибольшим ключом. Эта функция предполагает, что отображение не пусто.

Когда отображение не общее (или вызывается константная версия), это выполняется за логарифмическое время.

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

См. также first(), lastKey() и isEmpty().

[since 5.2] const T &QMap::last() const

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

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

[since 5.2] const Key &QMap::lastKey() const

Возвращает ссылку на наибольший ключ в отображении. Эта функция предполагает, что отображение не пусто.

Выполняется за логарифмическое время.

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

См. также firstKey(), last(), keyEnd() и isEmpty().

QMap::iterator QMap::lowerBound(const Key &key)

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

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

QMap::const_iterator QMap::lowerBound(const Key &key) const

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

QMap::size_type QMap::remove(const Key &key)

Удаляет все элементы, имеющие ключ key из отображения. Возвращает количество удаленных элементов, которое будет равно 1, если ключ существует в отображении, и 0 в противном случае.

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

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

Удаляет все элементы, для которых предикат pred возвращает true из отображения.

Функция поддерживает предикаты, принимающие аргумент типа QMap<Key, T>::iterator, или аргумент типа std::pair<const Key &, T &>.

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

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

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

QMap::size_type QMap::size() const

Возвращает количество пар (ключ, значение) в отображении.

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

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

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

T QMap::take(const Key &key)

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

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

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

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

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

Возвращает эквивалентную STL-карту для этой QMap.

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

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

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

Если в карте нет элемента с ключом key, функция вставляет значение, сконструированное по умолчанию, в карту с ключом key и возвращает ссылку на него. Если в карте есть несколько элементов с ключом key, эта функция возвращает ссылку на последнее вставленное значение.

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

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

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

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