std::multimap::multimap(3)

📦 version 2024.07.05, in nixpkgs unstable, opensuse-leap 16.0

🎀 std::multimap::multimap 🎀

okay bestie, welcome to the std::multimap::multimap(3) page from the C++ Standard Libary (header spelling and all 💅). this is your constructor buffet for std::multimap — every overload, every parameter, every caveat, and yes, every little defect report. no cap 💖

✨ NAME ✨

std::multimap::multimap — std::multimap::multimap (yes bestie, the name is literally the same as the thing, iconic 👑)

📜 Synopsis 📜

here's the whole signature lineup, kept exact:

          multimap();
       (until C++11)
          multimap()
       (since C++11)
              : multimap(Compare()) {}
          explicit multimap( const Compare& comp,                           (2)
                             const Allocator& alloc = Allocator() );
          explicit multimap( const Allocator& alloc );                      (3)
       (since C++11)
          template< class InputIt >

          multimap( InputIt first, InputIt last,                            (4)
                    const Compare& comp = Compare(),

                    const Allocator& alloc = Allocator() );
          template< class InputIt >

          multimap( InputIt first, InputIt last,                            (5)
       (since C++14)
                    const Allocator& alloc )

              : multimap(first, last, Compare(), alloc) {}
          multimap( const multimap& other );                                (6)
          multimap( const multimap& other, const Allocator& alloc );        (7)
       (since C++11)
          multimap( multimap&& other );                                     (8)
       (since C++11)
          multimap( multimap&& other, const Allocator& alloc );             (9)
       (since C++11)
          multimap( std::initializer_list<value_type> init,             (1)

                    const Compare& comp = Compare(),
       (10) (since C++11)

                    const Allocator& alloc = Allocator() );
          multimap( std::initializer_list<value_type> init,

                    const Allocator& alloc )
       (11) (since C++14)

              : multimap(init, Compare(), alloc) {}
          template< container-compatible-range<value_type> R >

          multimap( std::from_range_t, R&& rg,
       (12) (since C++23)
                    const Compare& comp = Compare(),

                    const Allocator& alloc = Allocator() );
          template< container-compatible-range<value_type> R >

          multimap( std::from_range_t, R&& rg,
                    const Allocator& alloc )
       (13) (since C++23)

              : multimap(std::from_range, std::forward<R>(rg),
          Compare(), alloc) {}

💬 Description 💬

Constructs new container from a variety of data sources and optionally using user supplied allocator alloc or comparison function object comp.

1-3) Constructs an empty container.
4,5) Constructs the container with the contents of the range [first, last).

If [first, last) is not a valid range, the behavior is undefined — like, do not do that, bestie 😭

6,7) Copy constructor. Constructs the container with the copy of the contents of other.

If alloc is not provided, allocator is obtained by calling std::allocator_traits<allocator_type>::select_on_container_copy_construction(other.get_allocator()) (since C++11). During class template argument deduction, only the first argument contributes to the deduction of the container's Allocator template parameter (since C++23).

8,9) Move constructor. Constructs the container with the contents of other using move semantics. If alloc is not provided, allocator is obtained by move-construction from the allocator belonging to other.

During class template argument deduction, only the first argument contributes to the deduction of the container's Allocator template parameter (since C++23).

10,11) Initializer-list constructor. Constructs the container with the contents of the initializer list init.
12,13) Constructs the container with the contents of rg.

🌸 Parameters 🌸

alloc — allocator to use for all memory allocations of this container.
comp — comparison function object to use for all comparisons of keys.
first, last — the range to copy the elements from.
other — another container to be used as source to initialize the elements of the container with.
init — initializer list to initialize the elements of the container with.
rg — a container compatible range, that is, an input_range whose elements are convertible to value_type.

🧚 Type requirements 🧚

InputIt must meet the requirements of LegacyInputIterator.
Compare must meet the requirements of Compare.
Allocator must meet the requirements of Allocator.

🔥 Complexity 🔥

1-3) Constant.
4,5) \(\scriptsize N \cdot log(N)\)N·log(N) where \(\scriptsize N\)N is std::distance(first, last) in general, linear in \(\scriptsize N\)N if [first, last) is already sorted by value_comp().
6,7) Linear in size of other.
8,9) Constant. If alloc is given and alloc != other.get_allocator(), then linear.
10,11) \(\scriptsize N \cdot log(N)\)N·log(N) where \(\scriptsize N\)N is init.size() in general, linear in \(\scriptsize N\)N if init is already sorted by value_comp().
12,13) \(\scriptsize N \cdot log(N)\)N·log(N) where \(\scriptsize N\)N is ranges::distance(rg) in general, linear in \(\scriptsize N\)N if rg is already sorted by value_comp().

😭 Exceptions 😭

Calls to Allocator::allocate may throw.

💅 Notes 💅

After container move construction (overload (8,9)), 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.

Although not formally required until C++23, some implementations has already put the template parameter Allocator into non-deduced contexts in earlier modes.

__cpp_lib_containers_ranges — 202202L — (C++23) — Ranges-aware construction and insertion; overloads (12,13).

🎀 Example 🎀

// Run this code

        #include <iostream>
        #include <map>
        #include <utility>

        struct Point { double x, y; };

        struct PointCmp
        {
            bool operator()(const Point& lhs, const Point& rhs) const
            {
                return lhs.x < rhs.x; // NB. ignores y on purpose
            }
        };

        template <typename Key, typename Value, typename Cmp>
        void println(auto rem, std::multimap<Key, Value, Cmp> const& map)
        {
            std::cout << rem << "{ ";
            for (auto n{map.size()}; auto const& p : map)
                std::cout << '[' << p.first << ":" << p.second << (--n ? "], "
       : "]");
            std::cout << " }\n";
        }

        int main()
        {
            std::multimap<int, int> m1 =
            {
                {1, 1}, {2, 2}, {3, 3}, {4, 4}, {4, 4}, {3, 3}, {2, 2}, {1, 1}
            };
            println("m1 = ", m1);

            // Custom comparison
            std::multimap<Point, double, PointCmp> mag
            {
                {{5, 12}, 13},
                {{3, 4}, 5},
                {{8, 15}, 17},
                {{3, -3}, -1}
            };
            for (auto p : mag)
                std::cout << "The magnitude of (" << p.first.x << ", " <<
       p.first.y << ")"
                             " is " << p.second << '\n';

            std::cout << "Construction from a range:\n";
            using PS = std::pair<int, std::string>;
            const auto rg = {PS{3, "Earth"}, {2, "Venus"}, {1, "Mercury"}, {3,
       "Moon"}};
        #if __cpp_lib_containers_ranges
            std::multimap<int, std::string> m2(std::from_range, rg); //
       overload (12)
        #else
            std::multimap<int, std::string> m2(rg.begin(), rg.end()); //
       fallback to (4)
        #endif
            println("m2 = ", m2);
        }

🌈 Output 🌈

m1 = { [1:1], [1:1], [2:2], [2:2], [3:3], [3:3], [4:4], [4:4] }
The magnitude of (3, 4) is 5
The magnitude of (3, -3) is -1
The magnitude of (5, 12) is 13
The magnitude of (8, 15) is 17
Construction from a range:
m2 = { [1:Mercury], [2:Venus], [3:Earth], [3:Moon] }

🦋 Defect reports 🦋

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

LWG 2076 — C++11 — overload (4) conditionally required Keyand T to be CopyInsertable into *this; correct behavior: not required.
LWG 2193 — C++11 — the default constructor was explicit; correct behavior: made non-explicit.

⭐ See also ⭐

operator= — assigns values to the container (public member function).

source/version/date check, bestie: this page is from http://cppreference.com, dated 2024.06.10, and it's the std::multimap::multimap(3) page. slay, go construct something cute 💖✨

📦 where this page comes from

nixpkgs unstable: stdman 2024.07.05
opensuse-leap 16.0: stdman 2024.07.05-bp160.1.9 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms