Класс 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 путем перемещения из other.

Эта функция была представлена в 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() в качестве подсказки, это указывает, что key меньше любого ключа в отображении, в то время как constEnd() предполагает, что key (строго) больше любого ключа в отображении. В противном случае подсказка должна удовлетворять условию (pos - 1).key() < key <= pos.key(). Если подсказка pos неверна, она игнорируется, и выполняется обычная вставка.

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

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

При создании карты из отсортированных данных вставка наибольшего ключа вначале с помощью 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().

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