Skip to content
C++: Inspect the keys left behind by map merge

C++: Inspect the keys left behind by map merge

November 11, 2026

Merging incoming records into an existing map should have an explicit duplicate-key policy. std::map::merge transfers keys that the destination does not already contain. Conflicting entries remain available in the source for inspection.

Prepare a scratch directory

Tested on Linux with GCC 14.2.0 in C++20 mode. You need Bash, a C++20 compiler and standard library, a text editor, and the mktemp, rm, and rmdir utilities. Keep the same terminal open. Stop if setup fails, before saving the source:

start_directory="$PWD"
work_directory="$(mktemp -d)" || exit 1
cd -- "$work_directory" || exit 1

Run the example

Save as cpp-map-merge-retain-conflicts.cpp:

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

int main() {
    std::map<std::string, int> current{{"alpha", 10}, {"beta", 20}};
    std::map<std::string, int> incoming{{"beta", 99}, {"gamma", 30}};
    current.merge(incoming);
    assert(current.size() == 3);
    assert(current.at("beta") == 20);
    assert(incoming.size() == 1 && incoming.at("beta") == 99);
    for (const auto& [name, value] : current) {
        std::cout << "current " << name << '=' << value << '\n';
    }
    for (const auto& [name, value] : incoming) {
        std::cout << "conflict " << name << '=' << value << '\n';
    }
    current.merge(incoming);
    assert(incoming.size() == 1);
    std::map<std::string, int> empty;
    current.merge(empty);
    assert(empty.empty() && current.size() == 3);
}

Compile and run:

g++ -std=c++20 -Wall -Wextra -Werror -pedantic cpp-map-merge-retain-conflicts.cpp -o cpp-map-merge-retain-conflicts &&
./cpp-map-merge-retain-conflicts

Observed output:

current alpha=10
current beta=20
current gamma=30
conflict beta=99

How it works

The destination keeps its existing value for the duplicate key. Repeating the merge without changing either map leaves the same conflict unresolved. Decide whether to reject or report the remaining source entries, or assign their values over the destination’s values.

This operation transfers nodes without copying their stored elements. The example uses matching default allocators. When using custom allocators, the source and destination allocators must compare equal; otherwise the merge has undefined behavior.

Limits and choices

Key uniqueness follows the destination comparator’s equivalence relation. With a custom case-insensitive comparator, differently spelled strings could conflict. Do not assume the source becomes empty, or that merge overwrites values. Avoid retaining source iterators as a way to traverse transferred elements afterward: transferred iterators refer into the destination. The program prints keys in the map’s sorted order, not their arrival order.

The C++ working draft describes map modifiers and the shared associative-container merge requirements. The example uses the C++20 interface tested above; newer draft additions are outside its scope.

Clean up

rm -- cpp-map-merge-retain-conflicts.cpp cpp-map-merge-retain-conflicts
cd -- "$start_directory" || exit 1
rmdir -- "$work_directory"
unset start_directory work_directory

If the directory is not empty, inspect the remaining files before removing anything else.

Acknowledgements

This post was created with assistance from AI.

Last updated on