home | help 
std::scoped...::construct(3)   C++ Standard Libary  std::scoped...::construct(3)

NAME
     std::scoped_allocator_adaptor::construct	 -   std::scoped_allocator_adap-
     tor::construct

Synopsis
	Defined in header <scoped_allocator>
	template< class T, class... Args >				   (1)
	void construct( T* p, Args&&... args );
	template< class T1, class T2, class... Args1, class... Args2 >

	void construct( std::pair<T1, T2>* p,
			std::piecewise_construct_t,			     (2)
     (until C++20)
			std::tuple<Args1...> x,

			std::tuple<Args2...> y );
	template<  class  T1, class T2 >				     (3)
     (until C++20)
	void construct( std::pair<T1, T2>* p );
	template< class T1, class T2, class U, class V	>		     (4)
     (until C++20)
	void construct( std::pair<T1, T2>* p, U&& x, V&& y );
	template<  class  T1, class T2, class U, class V >		     (5)
     (until C++20)
	void construct( std::pair<T1, T2>* p, const std::pair<U, V>& xy );
	template< class T1, class T2, class U, class V	>		     (6)
     (until C++20)
	void construct( std::pair<T1, T2>* p, std::pair<U, V>&& xy );
	template<  class  T1, class T2, class NonPair > 		     (7)
     (until C++20)
	void construct( std::pair<T1, T2>* p, NonPair&& non_pair );

	Constructs an object in allocated, but not initialized	storage  pointed
     to by p using
	OuterAllocator	and the provided constructor arguments. If the object is
     of type that
	itself uses allocators, or if it  is  std::pair,  passes  InnerAllocator
     down to the
	constructed object.

	First, retrieve the outermost allocator OUTERMOST by calling
	this->outer_allocator(),  and  then calling the outer_allocator() member
     function
	recursively on the result of this call until reaching an allocator  that
     has no such
	member function.

	Define OUTERMOST_ALLOC_TRAITS(x) as
	std::allocator_traits<std::remove_reference_t<decltype(OUTERMOST(x))>>

	1) Creates an object of the given type T by means of uses-allocator con-
     struction at
	the uninitialized memory location indicated by p, using OUTERMOST as the
     allocator.
	After adjustment for uses-allocator convention expected by T's construc-
     tor, calls
	OUTERMOST_ALLOC_TRAITS(*this)::construct.

	This  overload	participates  in  overload resolution only if U is not a
     (until C++20)
	specialization of std::pair.
	Equivalent to
	std::apply(

	    [p, this](auto&&... newargs)
	    {
		OUTERMOST_ALLOC_TRAITS(*this)::construct(
		    OUTERMOST(*this),					      p,
     (since C++20)
	std::forward<decltype(newargs)>(newargs)...);
	    },
	    std::uses_allocator_construction_args(
		inner_allocator(),
		std::forward<Args>(args)...
	    )
	);

	2)  First,  if either T1 or T2 is allocator-aware, modifies the tuples x
     and y
	to include the appropriate inner allocator, resulting in the two new tu-
     ples
	xprime and yprime, according to the following three rules:
	2a) if T1 is not allocator-aware
	(std::uses_allocator<T1, inner_allocator_type>::value  ==  false),  then
     xprime
	is std::tuple<Args1&&...>(std::move(x)). (It is also required that
	std::is_constructible<T1, Args1...>::value == true).
	2b) if T1 is allocator-aware (std::uses_allocator<T1,
	inner_allocator_type>::value  == true), and its constructor takes an al-
     locator
	tag

	std::is_constructible<T1, std::allocator_arg_t,
			      inner_allocator_type&, Args1...>::value == true,
	then xprime is

	std::tuple_cat(std::tuple<std::allocator_arg_t, inner_allocator_type&>(
			    std::allocator_arg, inner_allocator()
		       ),
		       std::tuple<Args1&&...>(std::move(x)))
	2c) if T1 is allocator-aware (std::uses_allocator<T1,
	inner_allocator_type>::value == true), and its constructor takes the
	allocator as the last argument

	std::is_constructible<T1,  Args1...,  inner_allocator_type&>::value   ==
     true,
	then xprime is

	std::tuple_cat(std::tuple<Args1&&...>(std::move(x)),
		       std::tuple<inner_allocator_type&>(inner_allocator())).
	Same rules apply to T2 and the replacement of y with yprime.
	Once  xprime  and yprime are constructed, constructs the pair p in allo-
     cated
	storage 			   by				 calling
     (until
	std::allocator_traits<O>::construct(OUTERMOST,
     C++20)
					    p,
					    std::piecewise_construct,
					    std::move(xprime),
					    std::move(yprime));
	3) Equivalent to

	construct(p, std::piecewise_construct, std::tuple<>(), std::tuple<>()),

	that  is,  passes  the	inner allocator on to the pair's member types if
     they
	accept them.
	4) Equivalent to
	construct(p, std::piecewise_construct,
	std::forward_as_tuple(std::forward<U>(x)),

	 std::forward_as_tuple(std::forward<V>(y)))
	5) Equivalent to
	construct(p, std::piecewise_construct, std::forward_as_tuple(xy.first),
					       std::forward_as_tuple(xy.second))
	6) Equivalent to
	construct(p, std::piecewise_construct,
		     std::forward_as_tuple(std::forward<U>(xy.first)),
		     std::forward_as_tuple(std::forward<V>(xy.second)))
	7) This overload participates in overload resolution only if 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 uneval-
     uated
	operand.

	Equivalent   to   construct<T1,   T2,	T1,   T2>(p,   std::forward<Non-
     Pair>(non_pair));.

Parameters
	p	 - pointer to allocated, but not initialized storage
	args...  - the constructor arguments to pass to the constructor of T
	x	 - the constructor arguments to pass to the constructor of T1
	y	 - the constructor arguments to pass to the constructor of T2
	xy	  - the pair whose two members are the constructor arguments for
     T1 and T2
	non_pair - non-pair argument to convert to pair for further construction

Return value
	(none)

Notes
	This function is called (through std::allocator_traits) by  any  alloca-
     tor-aware
	object,  such  as  std::vector,  that  was  given  a std::scoped_alloca-
     tor_adaptor as the
	allocator to use. Since inner_allocator is itself an instance of
	std::scoped_allocator_adaptor, this function will also	be  called  when
     the
	allocator-aware  objects  constructed  through	this function start con-
     structing their
	own members.

	Defect reports

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

	   DR	 Applied to	  Behavior as published 	     Correct be-
     havior
			    first overload is mistakenly used constrained to not
     accept
	LWG 2975 C++11	    for pair construction in some     pairs
			    cases
	P0475R1  C++11	    pair piecewise construction may   transformed to tu-
     ples of
			    copy   the	arguments		  references  to
     avoid copy
	LWG 3525 C++11	    no overload  could	handle	non-pair  reconstructing
     overload added
			    types convertible to pair

See also
	construct     constructs an object in the allocated storage
	[static]      (function template)
	construct     constructs an object in allocated storage
	(until C++20) (public member function of std::allocator<T>)

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