std::map<Key,T,Compare,Allocator>::operator[] (3) - Linux Manuals

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

NAME

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

Synopsis

T& operator[]( const Key& key ); (1)
T& operator[]( Key&& key ); (2) (since C++11)

Returns a reference to the value that is mapped to a key equivalent to key, performing an insertion if such key does not already exist.

1) Inserts value_type(key, T()) if the key does not exist. This function is equivalent to return insert(std::make_pair(key, T())).first->second;

-
key_type must meet the requirements of CopyConstructible. (until C++11)
-
mapped_type must meet the requirements of CopyConstructible and DefaultConstructible.

If an insertion is performed, the mapped value is value-initialized (default-constructed for class types, zero-initialized otherwise) and a reference to it is returned.
1) Inserts a value_type object constructed in-place from std::piecewise_construct, std::forward_as_tuple(key), std::tuple<>() if the key does not exist.
This function is equivalent to return this->try_emplace(key).first->second;.
(since C++17)
When the default allocator is used, this results in the key being copy constructed from key and the mapped value being value-initialized.

-
value_type must be EmplaceConstructible from std::piecewise_construct, std::forward_as_tuple(key), std::tuple<>(). When the default allocator is used, this means that key_type must be CopyConstructible and mapped_type must be DefaultConstructible.

2) Inserts a value_type object constructed in-place from std::piecewise_construct, std::forward_as_tuple(std::move(key)), std::tuple<>() if the key does not exist. (since C++11)
This function is equivalent to return this->try_emplace(std::move(key)).first->second;.
(since C++17)
When the default allocator is used, this results in the key being move constructed from key and the mapped value being value-initialized.

-
value_type must be EmplaceConstructible from std::piecewise_construct, std::forward_as_tuple(std::move(key)), std::tuple<>(). When the default allocator is used, this means that key_type must be MoveConstructible and mapped_type must be
DefaultConstructible.

No iterators or references are invalidated.

Parameters

key - the key of the element to find

Return value

Reference to the mapped value of the new element if no element with key key existed. Otherwise a reference to the mapped value of the existing element whose key is equivalent to key.

Exceptions

If an exception is thrown by any operation, the insertion has no effect

Complexity

Logarithmic in the size of the container.

Notes

In the published C++11 and C++14 standards, this function was specified to require mapped_type to be DefaultInsertable and key_type to be CopyInsertable or MoveInsertable into *this. This specification was defective and was fixed by LWG_issue_2469, and the description above incorporates the resolution of that issue.
However, one implementation (libc++) is known to construct the key_type and mapped_type objects via two separate allocator construct() calls, as arguably required by the standards as published, rather than emplacing a value_type object.
operator[] is non-const because it inserts the key if it doesn't exist. If this behavior is undesirable or if the container is const, at() may be used.

insert_or_assign() returns more information than operator[] and does not require default-constructibility of the mapped type. (since C++17)

Example

// Run this code

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

  int main()
  {
      std::map<char, int> letter_counts {{'a', 27}, {'b', 3}, {'c', 1}};

      std::cout << "initially:\n";
      for (const auto &pair : letter_counts) {
          std::cout << pair.first << ": " << pair.second << '\n';
      }

      letter_counts['b'] = 42; // update an existing value
      letter_counts['x'] = 9; // insert a new value

      std::cout << "after modifications:\n";
      for (const auto &pair : letter_counts) {
          std::cout << pair.first << ": " << pair.second << '\n';
      }

      // count the number of occurrences of each word
      // (the first call to operator[] initialized the counter with zero)
      std::map<std::string, size_t> word_map;
      for (const auto &w : { "this", "sentence", "is", "not", "a", "sentence",
                             "this", "sentence", "is", "a", "hoax"}) {
          ++word_map[w];
      }

      for (const auto &pair : word_map) {
          std::cout << pair.second << " occurrences of word '" << pair.first << "'\n";
      }
  }

Output:

  initially:
  a: 27
  b: 3
  c: 1
  after modifications:
  a: 27
  b: 42
  c: 1
  x: 9
  2 occurrences of word 'a'
  1 occurrences of word 'hoax'
  2 occurrences of word 'is'
  1 occurrences of word 'not'
  3 occurrences of word 'sentence'
  2 occurrences of word 'this'