home | help 
std::multimap::multimap(3)     C++ Standard Libary    std::multimap::multimap(3)

NAME
     std::multimap::multimap - std::multimap::multimap

Synopsis
	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) {}

	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.
	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
     (since
	std::allocator_traits<allocator_type>::
     C++11)
	    select_on_container_copy_construction(other.get_allocator()).
	During class template argument deduction, only the first  argument  con-
     tributes (since
	to  the  deduction  of	the  container's  Allocator  template parameter.
     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
     (since C++23)
	parameter.

	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 con-
     tainer
	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  con-
     tainer 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)\)NA.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)\)NA.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)\)NA.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,  point-
     ers, 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 al-
     ready put the
	template parameter Allocator into non-deduced contexts in earlier modes.

	    Feature-test macro	     Value    Std		    Feature
	__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 retroac-
     tively to
	previously published C++ standards.

	   DR	 Applied to		Behavior as published		    Cor-
     rect behavior
	LWG  2076  C++11      overload (4) conditionally required Keyand T   not
     required
			    to be CopyInsertable into *this
	LWG 2193 C++11	    the default constructor was explicit	    made
     non-explicit

See also
	operator= assigns values to the container
		  (public member function)

http://cppreference.com 	   2024.06.10	      std::multimap::multimap(3)
home | help