C++ map

last modified January 9, 2023

C++ map tutorial shows how to work with a map container in C++.

A map is a container which stores key/value pairs. A map is called an associative container, dictionary, or hash in other programming langauges.

Values in maps are referenced by their key and not by their absolute position in the container. The keys in a map are unique.

C++ map simple example

The following example shows some simple operations with a map.

#include <iostream>
#include <map>

using std::string;
using std::map;
using std::endl;
using std::cout;

int main() {

    map<int, string> stones {
      {1, "citrine"},
      {2, "garnet"},
      {3, "topaz"},
      {4, "opal"},
      {5, "ametyst"}
    };

    cout << stones.size() << endl;

    stones.insert({6, "spinel"});

    cout << stones.size() << endl;

    for (const auto& stone: stones) {

      cout << stone.first << ": " << stone.second << endl;
    }

    stones.clear();

    cout << stones.size() << endl;
}

We define a map of stones.

map<int, string> stones {
    {1, "citrine"},
    {2, "garnet"},
    {3, "topaz"},
    {4, "opal"},
    {5, "ametyst"}
};

In the stones map, the keys are integers and the values are strings.

cout << stones.size() << endl;

We get the size of the map with the size method.

stones.insert({6, "spinel"});

A new stone is inserted with the insert method.

for (const auto& stone: stones) {

    cout << stone.first << ": " << stone.second << endl;
}

We loop over the map with for-range loop.

stones.clear();

All pairs are removed with clear.

$ ./simple 
5
6
1: citrine
2: garnet
3: topaz
4: opal
5: ametyst
6: spinel
0

C++ map access elements

Values are accessed by their keys via [] operator or at method. Accessing a key which does not exist throws an exception.

#include <iostream>
#include <map>

using std::string;
using std::map;
using std::endl;
using std::cout;

int main() {

    map<int, string> stones {
      {1, "citrine"},
      {2, "garnet"},
      {3, "topaz"},
      {4, "opal"},
      {5, "ametyst"}
    };

    cout << stones.at(1) << endl;
    cout << stones[4] << endl;
}

We access two values from the stones map with [] and at.

$ ./access 
citrine
opal

C++ map update elements

The following example updates values.

#include <iostream>
#include <map>

using std::string;
using std::map;
using std::endl;
using std::cout;

int main() {

    map<int, string> words {
      {1, "sky"},
      {2, "blue"},
      {3, "cup"},
      {4, "nice"},
    };

    words[1] = "skylark";
    words.at(2) = "blues";

    for (const auto &word : words) {

        cout << "[" << word.first << ", " << word.second << "]" << endl;
    }
}

We update values of two pairs in the map using the assignment operator.

$ ./updating 
[1, skylark]
[2, blues]
[3, cup]
[4, nice]

C++ map erasing element

An element is deleted from a map with the erase method.

#include <iostream>
#include <map>

using std::string;
using std::map;
using std::endl;
using std::cout;

int main() {

    map<int, string> stones {
      {1, "citrine"},
      {2, "garnet"},
      {3, "topaz"},
      {4, "opal"},
      {5, "ametyst"}
    };

    stones.erase(4);

    for (const auto& stone: stones) {

      cout << stone.first << ": " << stone.second << endl;
    }
}

We delete a pair which has key 4.

$ ./erasing 
1: citrine
2: garnet
3: topaz
5: ametyst

C++ map erase_if

The erase_if method deletes all elements for which the given predicate returns true. The method was introduced in C++20.

#include <iostream>
#include <map>

using std::string;
using std::map;
using std::endl;
using std::cout;

int main() {
  
    map<int, string> words {
      {1, "sky"},
      {2, "blue"},
      {3, "cup"},
      {4, "nice"},
      {5, "tall"},
      {6, "car"},
      {7, "top"}
    };

    erase_if(words, [](const auto& e) {
        return (e.second.size() == 3);
    });

    for (const auto &word : words) {

        cout << "[" << word.first << ", " << word.second << "]" << endl;
    }
}

In the example, we remove all words from the map that have three characters.

$ clang++ erase_if.cpp -o erase_if -std=c++20
$ ./erase_if 
[2, blue]
[4, nice]
[5, tall]

C++ map merge

The merge method merges two maps. The method was introduced in C++20.

#include <iostream>
#include <map>

using std::string;
using std::map;
using std::endl;
using std::cout;

int main() {

    map<int, string> words {
      {1, "sky"},
      {2, "blue"},
      {3, "cup"}
    };

    map<int, string> words2 {
      {4, "nice"},
      {5, "tall"},
      {6, "car"},
      {7, "top"}
    };

    words.merge(words2);

    for (const auto &word : words) {

        cout << "[" << word.first << ", " << word.second << "]" << endl;
    }
}

We merge two maps of words.

$ ./merging 
[1, sky]
[2, blue]
[3, cup]
[4, nice]
[5, tall]
[6, car]
[7, top]

C++ map contains

The contains method checks if there is an element with the specified key.

#include <iostream>
#include <map>

using std::string;
using std::map;
using std::endl;
using std::cout;

int main()
{
    map<int, string> stones {
      {1, "citrine"},
      {2, "garnet"},
      {3, "topaz"},
      {4, "opal"},
      {5, "ametyst"}
    };

    for (int x: {2, 3, 7}) {
        if (stones.contains(x)) {
            cout << x << ": found" << endl;
        } else {
            cout << x << ": not found" << endl;
        }
    }
}

The contains method was introduced in C++20.

$ clang++ contains.cpp -o contains -std=c++20
$ ./contains 
2: found
3: found
7: not found

C++ map loop with while

The following example iterates over a map with while loop.

#include <iostream>
#include <map>

using std::cout;
using std::endl;
using std::string;
using std::map;

int main() {

    map<int, string> stones {
      {1, "citrine"},
      {2, "garnet"},
      {3, "topaz"},
      {4, "opal"},
      {5, "ametyst"}
    };

    auto it = stones.cbegin();

    while (it != stones.cend()) {

        cout << "[" << it->first << ", "
                    << it->second << "]\n";
        it++;
    }

    cout << endl;

    return 0;
}

The cbegin returns const iterator to the beginning and the cend to the end of the map.

$ ./while_loop 
[1, citrine]
[2, garnet]
[3, topaz]
[4, opal]
[5, ametyst]

C++ map loop with classic for

The following example loops over a map with the classic for form.

#include <iostream>
#include <map>

using std::cout;
using std::endl;
using std::string;
using std::map;

int main() {

    map<int, string> stones {
      {1, "citrine"},
      {2, "garnet"},
      {3, "topaz"},
      {4, "opal"},
      {5, "ametyst"}
    };

    for (auto it = stones.cbegin(); it != stones.cend(); it++) {

        cout << "[" << it->first << ", "
                    << it->second << "]"
                    << endl;
    }

    cout << endl;

    return 0;
}

We iterate over stones in the map with classic for loop.

C++ map loop with for range

The following example loops over map elements with for-range loop.

#include <iostream>
#include <map>

using std::cout;
using std::endl;
using std::string;
using std::map;

int main() {

    map<int, string> stones {
      {1, "citrine"},
      {2, "garnet"},
      {3, "topaz"},
      {4, "opal"},
      {5, "ametyst"}
    };

    for (const auto &stone : stones) {

        cout << "[" << stone.first << ", " << stone.second << "]\n";
    }

    cout << endl;

    return 0;
}

For-range loop was introduced in C++11.

The next example presents another for-range form.

#include <iostream>
#include <map>

using std::cout;
using std::endl;
using std::string;
using std::map;

int main() {

    map<int, string> stones {
      {1, "citrine"},
      {2, "garnet"},
      {3, "topaz"},
      {4, "opal"},
      {5, "ametyst"}
    };

    // decomposition C++17
    for (const auto& [key, value] : stones) {

        cout << "[" << key << ", " << value << "]\n";
    }

    cout << endl;

    return 0;
}

The decomposition operation used in this example was introduced in C++17.

In this article, we have worked with the map container in C++.