Класс QMap

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

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

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

Открытые типы

Открытые функции

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

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

Класс QMap — это шаблонный класс, предоставляющий словарь на основе красно-черного дерева.

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

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

• QHash обеспечивает в среднем более быстрый поиск, чем QMap. (Подробнее см. Сложность алгоритмов.)
• При итерации по QHash элементы упорядочиваются произвольно. В QMap элементы всегда упорядочены по ключу.
• Тип ключа QHash должен предоставлять оператор==() и глобальную функцию qHash(Ключ). Тип ключа 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 << 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() << endl;
}

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

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

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

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

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

Однако, вы можете хранить несколько значений на один ключ, используя insertMulti() вместо insert() (или используя удобный подкласс 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) << endl;

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

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

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

QMap<QString, int> map;
...
foreach (int value, map)
    cout << value << 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, const 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.

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

typedef QMap::ConstIterator

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

typedef QMap::Iterator

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

typedef QMap::difference_type

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

typedef QMap::key_type

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

typedef QMap::mapped_type

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

typedef QMap::size_type

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

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

QMap::QMap()

Конструирует пустую карту.

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

QMap::QMap(std::initializer_list<std::pair<Ключ, T> > list)

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

Эта функция доступна только если программа компилируется в режиме C++11.

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

QMap::QMap(const QMap<Ключ, T> &other)

Конструирует копию other.

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

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

QMap::QMap(QMap<Ключ, T> &&other)

Перемещающее конструирование экземпляра QMap, заставляя его указывать на тот же объект, на который указывал other.

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

QMap::QMap(const std::map<Ключ, T> &other)

Конструирует копию other.

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

QMap::~QMap()

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

iterator QMap::begin()

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

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

const_iterator QMap::begin() const

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

const_iterator QMap::cbegin() const

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

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

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

const_iterator QMap::cend() const

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

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

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

void QMap::clear()

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

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

const_iterator QMap::constBegin() const

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

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

const_iterator QMap::constEnd() const

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

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

const_iterator QMap::constFind(const Ключ &key) const

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

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

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

См. также find() и QMultiMap::constFind().

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

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

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

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

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

См. также contains(), insertMulti(), и QMultiMap::count().

int QMap::count() const

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

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

bool QMap::empty() const

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

iterator QMap::end()

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

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

const_iterator QMap::end() const

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

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

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

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

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

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

iterator QMap::erase(iterator pos)

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

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

iterator QMap::find(const Key &key)

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

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

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

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

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

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

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

T &QMap::first()

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

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

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

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

const T &QMap::first() const

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

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

const Key &QMap::firstKey() const

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

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

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

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

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

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

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

Если есть несколько элементов с ключом key, значение последнего вставленного элемента заменяется на value.

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

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

Если есть несколько элементов с ключом key, ровно один из них заменяется на value.

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

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

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

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

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

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

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

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

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

iterator QMap::insertMulti(const_iterator pos, const Key &key, const T &value)

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

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

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

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

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

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

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

bool QMap::isEmpty() const

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

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

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

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

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

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

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

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

key_iterator QMap::keyBegin() const

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

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

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

key_iterator QMap::keyEnd() const

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

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

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

QList<Key> QMap::keys() const

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

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

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

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

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

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

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

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

T &QMap::last()

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

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

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

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

const T &QMap::last() const

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

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

const Key &QMap::lastKey() const

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

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

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

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

iterator QMap::lowerBound(const Key &key)

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

Пример:

QMap<int, QString> map;
map.insert(1, "one");
map.insert(5, "five");
map.insert(10, "ten");

map.lowerBound(0);      // returns iterator to (1, "one")
map.lowerBound(1);      // returns iterator to (1, "one")
map.lowerBound(2);      // returns iterator to (5, "five")
map.lowerBound(10);     // returns iterator to (10, "ten")
map.lowerBound(999);    // returns end()

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

QMap<QString, int> map;
...
QMap<QString, int>::const_iterator i = map.lowerBound("HDR");
QMap<QString, int>::const_iterator upperBound = map.upperBound("HDR");
while (i != upperBound) {
    cout << i.value() << endl;
    ++i;
}

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

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

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

int QMap::remove(const Key &key)

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

См. также clear(), take() и QMultiMap::remove().

int QMap::size() const

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

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

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

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

Функция была добавлена в Qt 4.8.

T QMap::take(const Key &key)

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

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

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

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

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

Возвращает эквивалентное отображению STL.

QList<Key> QMap::uniqueKeys() const

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

Функция была добавлена в Qt 4.2.

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

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

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

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

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

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

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

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

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

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

См. также key(), values(), contains() и operator[]().

QList<T> QMap::values() const

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

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

QList<T> QMap::values(const Key &key) const

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

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

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

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

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

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

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

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

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

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

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

Перемещающее присваивание other этому отображению QMap.

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

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

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

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

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

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

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

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

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

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

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

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

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