std::unordered_map::operator[]

mapped_type& operator[] ( const key_type& k );mapped_type& operator[] ( key_type&& k );

Access element

If k matches the key of an element in the container, the function returns a reference to its mapped value.

If k does not match the key of any element in the container, the function inserts a new element with that key and returns a reference to its mapped value. Notice that this always increases the container size by one, even if no mapped value is assigned to the element (the element is constructed using its default constructor).

A similar member function, unordered_map::at, has the same behavior when an element with the key exists, but throws an exception when it does not.

Parameters

k: Key value of the element whose mapped value is accessed.
Member type key_type is the type of the keys for the elements stored in the container, defined in unordered_map as an alias of its first template parameter (Key).
If an rvalue (second version), the key is moved instead of copied when a new element is inserted.

Return value

A reference to the mapped value of the element with a key value equivalent to k.
Member type mapped_type is the type of the mapped values in the container, defined in unordered_map as an alias of its second template parameter (T).

If a new element is inserted, its storage is allocated using allocator_traits<allocator_type>::construct(), which may throw exceptions on failure (for the default allocator, bad_alloc is thrown if the allocation request does not succeed).

Example

// unordered_map::operator[]
#include <iostream>
#include <string>
#include <unordered_map>

int main ()
{
  std::unordered_map<std::string,std::string> mymap;

  mymap["Bakery"]="Barbara";  // new element inserted
  mymap["Seafood"]="Lisa";    // new element inserted
  mymap["Produce"]="John";    // new element inserted

  std::string name = mymap["Bakery"];   // existing element accessed (read)
  mymap["Seafood"] = name;              // existing element accessed (written)

  mymap["Bakery"] = mymap["Produce"];   // existing elements accessed (read/written)

  name = mymap["Deli"];      // non-existing element: new element "Deli" inserted!

  mymap["Produce"] = mymap["Gifts"];    // new element "Gifts" inserted, "Produce" written

  for (auto& x: mymap) {
    std::cout << x.first << ": " << x.second << std::endl;
  }

  return 0;
}

Possible output:

Seafood: Barbara
Deli:
Bakery: John
Gifts:
Produce:

Complexity

Average case: constant.
Worst case: linear in container size.

May trigger a rehash if an element is inserted (not included in the complexity above).

Iterator validity

On most cases, all iterators in the container remain valid after the insertion. The only exception being when this function inserts a new element and this forces a rehash. In this case, all iterators in the container are invalidated.

A rehash is forced if the new container size after the insertion operation would increase above its capacity threshold (calculated as the container's bucket_count multiplied by its max_load_factor).

References to elements in the unordered_map container remain valid in all cases, even after a rehash.

member functions

non-member overloads