Spec-Zone.ru › C++

std::map<Key,T,Compare,Allocator>::operator[]

T& operator[]( const Key& key );
(1)
T& operator[]( Key&& key );
(2) (начиная с C++11)
template< class K >
T& operator[]( K&& x );
(3) (начиная с C++26)

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

1) Вставляет value_type(key, T()), если ключ не существует.
-key_type должен соответствовать требованиям CopyConstructible.
-mapped_type должен соответствовать требованиям CopyConstructible и DefaultConstructible.
Если выполняется вставка, отображаемое значение инициализируется значением (для типов классов конструируется по умолчанию, для остальных типов инициализируется нулём), после чего возвращается ссылка на него.
(до C++11)
1) Вставляет объект value_type, сконструированный на месте из std::piecewise_construct, std::forward_as_tuple(key), std::tuple<>(), если ключ не существует. Эквивалентно return this->try_emplace(key).first->second;.(начиная с C++17)При использовании распределителя по умолчанию ключ копирующим конструктором создаётся из key, а отображаемое значение инициализируется значением.
-value_type должен быть EmplaceConstructible из std::piecewise_construct, std::forward_as_tuple(key), std::tuple<>(). При использовании распределителя по умолчанию это означает, что key_type должен быть CopyConstructible, а mapped_type должен быть DefaultConstructible.
2) Вставляет объект value_type, сконструированный на месте из std::piecewise_construct, std::forward_as_tuple(std::move(key)), std::tuple<>(), если ключ не существует. Эквивалентно return this->try_emplace(std::move(key)).first->second;.(начиная с C++17)
При использовании распределителя по умолчанию ключ перемещающим конструктором создаётся из key, а отображаемое значение инициализируется значением.
-value_type должен быть EmplaceConstructible из std::piecewise_construct, std::forward_as_tuple(std::move(key)), std::tuple<>(). При использовании распределителя по умолчанию это означает, что key_type должен быть MoveConstructible, а mapped_type должен быть DefaultConstructible.
(начиная с C++11)
3) Вставляет объект value_type, сконструированный на месте, если нет ключа, который прозрачно сравнивается как эквивалентный значению x.
Эквивалентно return this->try_emplace(std::forward<K>(x)).first->second;. Эта перегрузка участвует в разрешении перегрузки, только если qualified-id Compare::is_transparent допустим и обозначает тип. Это позволяет вызвать эту функцию без создания экземпляра Key.

Итераторы и ссылки не становятся недействительными.

Параметры

key - ключ искомого элемента
x - значение любого типа, которое можно прозрачно сравнить с ключом

Возвращаемое значение

1,2) Ссылка на отображаемое значение нового элемента, если элемента с ключом key не существовало. В противном случае — ссылка на отображаемое значение существующего элемента, ключ которого эквивалентен key.
3) Ссылка на отображаемое значение нового элемента, если элемента с ключом, сравниваемым как эквивалентный значению x, не существовало. В противном случае — ссылка на отображаемое значение существующего элемента, ключ которого сравнивается как эквивалентный x.

Исключения

Если какая-либо операция выбрасывает исключение, вставка не выполняется.

Сложность

Логарифмическая относительно размера контейнера.

Примечания

В опубликованных стандартах C++11 и C++14 для этой функции требовалось, чтобы mapped_type удовлетворял требованиям DefaultInsertable, а key_type — требованиям CopyInsertable или MoveInsertable в *this. Эта спецификация была некорректной и исправлена в предложении LWG 2469; приведённое выше описание учитывает это исправление.

Однако известно, что одна реализация (libc++) конструирует объекты key_type и mapped_type с помощью двух отдельных вызовов распределителя construct(), что, возможно, требуется опубликованными стандартами, вместо помещения объекта value_type в контейнер.

operator[] не является константным, поскольку вставляет ключ, если тот не существует. Если такое поведение нежелательно или контейнер является const, можно использовать at.

insert_or_assign возвращает больше информации, чем operator[], и не требует, чтобы отображаемый тип был конструируемым по умолчанию.

(начиная с C++17)
Макрос проверки поддержки возможностей Значение Стандарт Возможность
__cpp_lib_associative_heterogeneous_insertion 202311L (C++26) Гетерогенные перегрузки для остальных функций-членов упорядоченных ассоциативных контейнеров и неупорядоченных ассоциативных контейнеров. (3)

Пример

#include <iostream>
#include <string>
#include <map>

void println(auto const comment, auto const& map)
{
    std::cout << comment << '{';
    for (const auto& pair : map)
        std::cout << '{' << pair.first << ": " << pair.second << '}';
    std::cout << "}\n";
}

int main()
{
    std::map<char, int> letter_counts{{'a', 27}, {'b', 3}, {'c', 1}};
    
    println("letter_counts initially contains: ", letter_counts);
    
    letter_counts['b'] = 42; // updates an existing value
    letter_counts['x'] = 9;  // inserts a new value
    
    println("after modifications it contains: ", letter_counts);
    
    // count the number of occurrences of each word
    // (the first call to operator[] initialized the counter with zero)
    std::map<std::string, int>  word_map;
    for (const auto& w : {"this", "sentence", "is", "not", "a", "sentence",
                          "this", "sentence", "is", "a", "hoax"})
        ++word_map[w];
    word_map["that"]; // just inserts the pair {"that", 0}
    
    for (const auto& [word, count] : word_map)
        std::cout << count << " occurrence(s) of word '" << word << "'\n";
}

Вывод:

letter_counts initially contains: {{a: 27}{b: 3}{c: 1}}
after modifications it contains: {{a: 27}{b: 42}{c: 1}{x: 9}}
2 occurrence(s) of word 'a'
1 occurrence(s) of word 'hoax'
2 occurrence(s) of word 'is'
1 occurrence(s) of word 'not'
3 occurrence(s) of word 'sentence'
0 occurrence(s) of word 'that'
2 occurrence(s) of word 'this'

Отчёты об ошибках

Следующие отчёты об ошибках, изменяющие поведение, были ретроактивно применены к ранее опубликованным стандартам C++.

DR Применён к Опубликованное поведение Правильное поведение
LWG 334 C++98 эффект перегрузки (1) заключался лишь в возврате
(*((insert(std::make_pair(x, T()))).first)).second
вместо этого было приведено
отдельное описание

См. также

at
доступ к указанному элементу с проверкой границ
(открытая функция-член)
insert_or_assign
(C++17)
вставляет элемент или присваивает значение существующему элементу, если ключ уже существует
(открытая функция-член)
try_emplace
(C++17)
вставляет элемент на месте, если ключ не существует; ничего не делает, если ключ существует
(открытая функция-член)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/container/map/operator_at

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API