Класс QMap

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

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

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

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

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

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

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

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

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

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

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

QMap<QString, int> map;

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

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

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

map.insert("twelve", 12);

Для поиска значения используйте operator[]() или 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() для поиска ключа в карте вместо operator[](). Причина в том, что operator[]() молча вставляет элемент в карту, если элемент с таким же ключом не существует (если карта не является константной). Например, следующий фрагмент кода создаст 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 должен предоставлять operator<(). 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()

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

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

Этот метод был добавлен в 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.

Эта функция была добавлена в 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

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

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

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

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

Возвращает 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

Возвращает 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

Возвращает 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()

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

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

Эта функция была добавлена в 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().