home | help
std::uses_a...ruction_args(3)  C++ Standard Libary std::uses_a...ruction_args(3)

NAME
     std::uses_allocator_construction_args    -    std::uses_allocator_construc-
     tion_args

Synopsis
	Defined in header <memory>
	T is not a specialization of std::pair
	template< class T, class Alloc, class... Args >

	constexpr auto uses_allocator_construction_args( const	Alloc&	     (1)
     (since C++20)
	alloc,

	    Args&&... args ) noexcept;
	T is a specialization of std::pair
	template< class T, class Alloc, class Tuple1, class Tuple2 >

	constexpr  auto  uses_allocator_construction_args( const Alloc&      (2)
     (since C++20)
	alloc,

	    std::piecewise_construct_t, Tuple1&& x, Tuple2&& y ) noexcept;
	template< class T, class Alloc >
	constexpr auto uses_allocator_construction_args( const	Alloc&	     (3)
     (since C++20)
	alloc ) noexcept;
	template< class T, class Alloc, class U, class V >

	constexpr  auto  uses_allocator_construction_args( const Alloc&      (4)
     (since C++20)
	alloc,

	    U&& u, V&& v ) noexcept;
	template< class T, class Alloc, class U, class V >

	constexpr auto uses_allocator_construction_args( const	Alloc&	     (5)
     (since C++23)
	alloc,

	    std::pair<U, V>& pr ) noexcept;
	template< class T, class Alloc, class U, class V >

	constexpr  auto  uses_allocator_construction_args( const Alloc&      (6)
     (since C++20)
	alloc,

	    const std::pair<U, V>& pr ) noexcept;
	template< class T, class Alloc, class U, class V >

	constexpr auto uses_allocator_construction_args( const	Alloc&	     (7)
     (since C++20)
	alloc,

	    std::pair<U, V>&& pr ) noexcept;
	template< class T, class Alloc, class U, class V >

	constexpr  auto  uses_allocator_construction_args( const Alloc&      (8)
     (since C++23)
	alloc,

	    const std::pair<U, V>&& pr ) noexcept;
	template< class T, class Alloc, class NonPair >

	constexpr auto uses_allocator_construction_args( const	Alloc&	     (9)
     (since C++20)
	alloc,

	    NonPair&& non_pair ) noexcept;

	Prepares  the argument list needed to create an object of the given type
     T by means
	of uses-allocator construction.

	1) This overload participates in overload resolution only if T is not a
	specialization of std::pair. Returns std::tuple determined as follows:
	  *  If  std::uses_allocator_v<T,  Alloc>  is  false  and   std::is_con-
     structible_v<T,
	    Args...>	is    true,    returns	 std::forward_as_tuple(std::for-
     ward<Args>(args)...).
	  * Otherwise, if std::uses_allocator_v<T, Alloc> is true and
	    std::is_constructible_v<T,	 std::allocator_arg_t,	 const	 Alloc&,
     Args...> is true,
	    returns
	    std::tuple<std::allocator_arg_t, const Alloc&, Args&&...>(std::allo-
     cator_arg,
	    alloc,

	    std::forward<Args>(args)...).
	  * Otherwise, if std::uses_allocator_v<T, Alloc> is true and
	    std::is_constructible_v<T, Args..., const Alloc&> is true, returns
	    std::forward_as_tuple(std::forward<Args>(args)..., alloc).
	  * Otherwise, the program is ill-formed.
	2) This overload participates in overload resolution only if T is a spe-
     cialization
	of std::pair. For T that is std::pair<T1, T2>, equivalent to

      return std::make_tuple(std::piecewise_construct,
	  std::apply([&alloc](auto&&... args1)
	      {
		  return std::uses_allocator_construction_args<T1>(alloc,
			     std::forward<decltype(args1)>(args1)...);
	      }, std::forward<Tuple1>(x)
	  ),
	  std::apply([&alloc](auto&&... args2)
	      {
		  return std::uses_allocator_construction_args<T2>(alloc,
			     std::forward<decltype(args2)>(args2)...);
	      }, std::forward<Tuple2>(y)
	  )
      );

	3) This overload participates in overload resolution only if T is a spe-
     cialization
	of std::pair. Equivalent to

      return std::uses_allocator_construction_args<T>(alloc,
	  std::piecewise_construct, std::tuple<>{}, std::tuple<>{}
      );

	4) This overload participates in overload resolution only if T is a spe-
     cialization
	of std::pair. Equivalent to

      return std::uses_allocator_construction_args<T>(alloc,
	  std::piecewise_construct,
	  std::forward_as_tuple(std::forward<U>(u)),
	  std::forward_as_tuple(std::forward<V>(v))
      );

	5,6)  This  overload  participates in overload resolution only if T is a
     specialization
	of std::pair. Equivalent to

      return std::uses_allocator_construction_args<T>(alloc,
	  std::piecewise_construct,
	  std::forward_as_tuple(pr.first),
	  std::forward_as_tuple(pr.second)
      );

	7,8) This overload participates in overload resolution only if	T  is  a
     specialization
	of std::pair. Equivalent to

      return std::uses_allocator_construction_args<T>(alloc,
	  std::piecewise_construct,
	  std::forward_as_tuple(std::get<0>(std::move(pr))),
	  std::forward_as_tuple(std::get<1>(std::move(pr)))
      );

	9) This overload participates in overload resolution only if T is a spe-
     cialization
	of std::pair, and given the exposition-only function template

      template<class A, class B>
      void /*deduce-as-pair*/(const std::pair<A, B>&);

	,  /*deduce-as-pair*/(non_pair)  is ill-formed when considered as an un-
     evaluated
	operand.
	Let the exposition-only class pair-constructor be defined as

      class /*pair-constructor*/
      {
	  const Alloc& alloc_; // exposition only
	  NonPair&     u_;     // exposition only

	  constexpr reconstruct(const std::remove_cv<T>& p) const //  exposition
     only
	  {
	      return	std::make_obj_using_allocator<std::remove_cv<T>>(alloc_,
     p);
	  }

	  constexpr reconstruct(std::remove_cv<T>&& p) const // exposition only
	  {
	      return	std::make_obj_using_allocator<std::remove_cv<T>>(alloc_,
     std::move(p));
	  }

      public:
	  constexpr operator std::remove_cv<T>() const
	  {
	      return reconstruct(std::forward<NonPair>(u_));
	  }
      };

	This  overload	is  equivalent	to return std::make_tuple(pair_construc-
     tion);, where
	pair_construction is a value of type pair-constructor whose  alloc_  and
     u_ members
	are alloc and non_pair respectively.

Parameters
	alloc	 - the allocator to use
	args	 - the arguments to pass to T's constructor
	x	  -  tuple of arguments to pass to the constructors of T's first
     data member
	y	 - tuple of arguments to pass to the constructors of T's  second
     data member
	u	  - single argument to pass to the constructor of T's first data
     member
	v	 - single argument to pass to the constructor of T's second data
     member
		   a pair whose first data member will be  passed  to  the  con-
     structor of T's
	pr	  -  first  data member and second data member will be passed to
     the
		   constructor of T's second data member
	non_pair - single argument to convert to a std::pair  for  further  con-
     struction

Return value
	std::tuple of arguments suitable for passing to the constructor of T.

Notes
	The  overloads (2-9) provide allocator propagation into std::pair, which
     supports
	neither leading-allocator  nor	trailing-allocator  calling  conventions
     (unlike, e.g.
	std::tuple, which uses leading-allocator convention).

	When used in uses-allocator construction, the conversion function of
	pair-constructor  converts  the provided argument to std::pair at first,
     and then
	constructs the result from that std::pair  by  uses-allocator  construc-
     tion.

Example
	 This section is incomplete
	 Reason: no example

	Defect reports

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

	   DR	 Applied to	     Behavior as published		 Correct
     behavior
	LWG  3525  C++20       no  overload  could handle non-pair types  recon-
     structing overload
			    convertible to pair 		     added

See also
	uses_allocator				checks	if  the  specified  type
     supports
	(C++11) 				uses-allocator construction
						(class template)
	make_obj_using_allocator		 creates  an object of the given
     type by means
	(C++20) 				of uses-allocator construction
						(function template)
						creates an object of  the  given
     type at
	uninitialized_construct_using_allocator  specified  memory  location  by
     means of
	(C++20) 				uses-allocator construction
						(function template)

Category:
	  * Todo no example

http://cppreference.com 	   2024.06.10	   std::uses_a...ruction_args(3)

home | help