std::map::operator=(3)

💅 std::map::operator=(3)

ok so this is std::map::operator=, page 3 of the C++ Standard Library man pages — and yes, bestie, the manual name is literally "C++ Standard Libary" up top in the original (typo and all, we don't gatekeep spelling slay 💀). Anyway. Sit down, hydrate, let's learn how to overwrite a whole map.

---

✨ NAME ✨

std::map::operator= — it's giving "assignment operator for std::map", and it's exactly what it says on the tin 🎀

---

🦋 Synopsis 🦋

map& operator=( const map& other );                        (1)
map& operator=( map&& other );
(since C++11)
                                                           (2)
(until C++17)
map& operator=( map&& other ) noexcept(/* see below */);
(since C++17)
map& operator=( std::initializer_list<value_type> ilist );     (3)
(since C++11)

🙈 yeah the version markers came out a lil scrambled in the original — that's how they're printed, so I'm keeping them exactly as-is. (2) is the move-assign one, and it picks up that noexcept clause once you're on C++17.

---

🌸 Description 🌸

The whole vibe of this function is one sentence: it replaces the contents of the container. That's it. That's the main character energy 👑

So, the three overloads:

1) Copy assignment operator. Replaces the contents with a copy of the contents of other.

And now the allocator lore, because of course there's allocator lore 🧚:

If std::allocator_traits<allocator_type>::propagate_on_container_copy_assignment::value is true, the allocator of *this is replaced by a copy of other. And if the allocator of *this after assignment would compare unequal to its old value, then the old allocator is (since C++11) used to deallocate the memory, and then the new allocator is used to allocate it before (until C++11) copying the elements. Otherwise, the memory owned by *this may be reused when possible. In any case, the elements originally belonging to *this may be either destroyed or replaced by element-wise copy-assignment.

(translation: sometimes it reuses memory, sometimes it nukes and reallocates, and you don't get to pick 😌)

2) Move assignment operator. Replaces the contents with those of other using move semantics — i.e. the data in other is moved from other into this container. After that, other is in a valid but unspecified state. Yes, valid-but-unspecified. She's fine, she's just not gonna tell you how fine 💀

If std::allocator_traits<allocator_type>::propagate_on_container_move_assignment::value is true, the allocator of *this is replaced by a copy of that of other. If it is false and the allocators of *this and other do not compare equal, then *this cannot take ownership of the memory owned by other, and it must move-assign each element individually, allocating additional memory using its own allocator as needed. In any case, all elements originally belonging to *this are either destroyed or replaced by element-wise move-assignment.

3) Replaces the contents with those identified by initializer list ilist. Cute, quick, one-liner energy ✨

---

🎀 Parameters 🎀

• other — another container to use as data source 🫶
• ilist — initializer list to use as data source 🌈

---

💖 Return value 💖

*this

(no cap, she returns herself. main character behaviour.)

---

🔥 Complexity 🔥

1. Linear in the size of *this and other.
2. Linear in the size of *this — unless the allocators do not compare equal and do not propagate, in which case it's linear in the size of *this and other.
3. O(NlogN) in general, where N is size() + ilist.size(). Linear if ilist is sorted with respect to value_comp().

💅 iykyk: sort your init list first and you basically skip the log. free real estate.

---

😭 Exceptions 😭

1-3) May throw implementation-defined exceptions. (until C++17)

(since C++17) 1,3) May throw implementation-defined exceptions.

2) noexcept specification:

noexcept(std::allocator_traits<Allocator>::is_always_equal::value
&& std::is_nothrow_move_assignable<Compare>::value)

---

🦋 Notes 🦋

After container move assignment — that's overload (2) — unless element-wise move assignment is forced by incompatible allocators, references, pointers, and iterators (other than the end iterator) to other remain valid, but refer to elements that are now in *this.

The current standard makes this guarantee via the blanket statement in [container.reqmts]/67, and a more direct guarantee is under consideration via LWG issue 2321.

🌸 so like… your iterators survive the move? they just moved house. they live in *this now. rude but iconic.

---

🌈 Example 🌈

The following code uses operator= to assign one std::map to another:

// Run this code

#include <initializer_list>
#include <iostream>
#include <iterator>
#include <map>
#include <utility>

void print(auto const comment, auto const& container)
{
    auto size = std::size(container);
    std::cout << comment << "{ ";
    for (auto const& [key, value] : container)
        std::cout << '{' << key << ',' << value << (--size ? "}, " : "} ");
    std::cout << "}\n";
}

int main()
{
    std::map<int, int> x{{1,1}, {2,2}, {3,3}}, y, z;
    const auto w = {std::pair<const int, int>{4,4}, {5,5}, {6,6}, {7,7}};

    std::cout << "Initially:\n";
    print("x = ", x);
    print("y = ", y);
    print("z = ", z);

    std::cout << "Copy assignment copies data from x to y:\n";
    y = x;
    print("x = ", x);
    print("y = ", y);

    std::cout << "Move assignment moves data from x to z, modifying both x and z:\n";
    z = std::move(x);
    print("x = ", x);
    print("z = ", z);

    std::cout << "Assignment of initializer_list w to z:\n";
    z = w;
    print("w = ", w);
    print("z = ", z);
}

---

⭐ Output ⭐

Initially:
x = { {1,1}, {2,2}, {3,3} }
y = { }
z = { }
Copy assignment copies data from x to y:
x = { {1,1}, {2,2}, {3,3} }
y = { {1,1}, {2,2}, {3,3} }
Move assignment moves data from x to z, modifying both x and z:
x = { }
z = { {1,1}, {2,2}, {3,3} }
Assignment of initializer_list w to z:
w = { {4,4}, {5,5}, {6,6}, {7,7} }
z = { {4,4}, {5,5}, {6,6}, {7,7} }

💀 not x getting absolutely emptied out by the move. she gave everything she had. respect.

---

👑 See also 👑

• constructor — constructs the map (public member function) 🫶

---

🧚 Category 🧚

• conditionally noexcept

---

ok that's the whole page, you ate that 🍓 go forth and reassign your maps responsibly. this little writeup came from http://cppreference.com, dated 2024.06.10, and it's the std::map::operator=(3) page — mwah, love u, bye 💜✨