Класс 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.

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

typedef QMap::ConstIterator

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

typedef QMap::Iterator

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

typedef QMap::const_key_value_iterator

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

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

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

См. также QKeyValueIterator.

typedef QMap::difference_type

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

typedef QMap::key_type

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

typedef QMap::key_value_iterator

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

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

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

См. также QKeyValueIterator.

typedef QMap::mapped_type

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

typedef QMap::size_type

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

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

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

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

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

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

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

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

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

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

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

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

QMap::QMap(std::initializer_list<std::pair<Key, T> > list)

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

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

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

QMap::QMap()

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

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

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

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

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

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

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

QMap::~QMap()

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

QMap::iterator QMap::begin()

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

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

QMap::const_iterator QMap::begin() const

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

QMap::const_iterator QMap::cbegin() const

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

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

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

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

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

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

QMap::const_key_value_iterator QMap::constKeyValueBegin() const

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

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

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

QMap::const_key_value_iterator QMap::constKeyValueEnd() const

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

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

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

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

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

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

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

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

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

int 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.

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

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

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

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

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

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

QMap::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() << Qt::endl;
    ++i;
}

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

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

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

Вставляет новую запись с ключом key и значением value.

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

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

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

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.

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

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

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

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

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

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

void QMap::insert(const QMap<Key, T> &map)

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

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

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

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

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

bool QMap::isEmpty() const

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

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

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

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

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

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

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

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

QMap::key_iterator QMap::keyBegin() const

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

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

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

QMap::key_iterator QMap::keyEnd() const

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

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

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

QMap::key_value_iterator QMap::keyValueBegin()

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

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

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

QMap::const_key_value_iterator QMap::keyValueBegin() const

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

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

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

QMap::key_value_iterator QMap::keyValueEnd()

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

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

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

QMap::const_key_value_iterator QMap::keyValueEnd() const

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

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

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

QList<Key> QMap::keys() const

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

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

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

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

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

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

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

T &QMap::last()

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

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

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

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

const T &QMap::last() const

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

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

const Key &QMap::lastKey() const

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

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

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

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

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

Возвращает итератор, указывающий на первый элемент с ключом key в map. Если map не содержит элемента с ключом 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()

Если map содержит несколько элементов с ключом 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() << Qt::endl;
    ++i;
}

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

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

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

int QMap::remove(const Key &key)

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

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

int QMap::size() const

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

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

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

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

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

T QMap::take(const Key &key)

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

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

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

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

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

Возвращает эквивалентный STL map для этого QMap.

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

Возвращает итератор, указывающий на элемент, который сразу следует за последним элементом с ключом key в map. Если map не содержит элемента с ключом 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

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

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

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

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

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

QList<T> QMap::values() const

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

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

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

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

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

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

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

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