Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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() mem-
       ber 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(OUTER-
       MOST(x))>>

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

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

	  std::apply(
	      [p,this](auto&&... newargs) {
		  OUTERMOST_ALLOC_TRAITS(*this)::construct(
		      OUTERMOST(*this),		  p,	      std::forward<de-
       cltype(newargs)>(newargs)...); (since
	      },
       C++20)
	      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_alloca-
       tor_type&,
	 Args1...>::value==true), then xprime is

	 std::tuple_cat(std::tuple<std::allocator_arg_t,	 inner_alloca-
       tor_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  al-
       located
	 storage by calling

	 std::allocator_traits<O>::construct( OUTERMOST,
					      p,
					      std::piecewise_construct,
					      std::move(xprime),
       (until
					      std::move(yprime));
       C++20)

	 3)  Equivalent	 to  construct(p,  std::piecewise_construct,  std::tu-
       ple<>(),
	 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_tu-
       ple(std::forward<U>(x)),
						std::forward_as_tu-
       ple(std::forward<V>(y)))

	 5) Equivalent to

	 construct(p,	    std::piecewise_construct,	   std::forward_as_tu-
       ple(xy.first),
						std::forward_as_tuple(xy.sec-
       ond))

	 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
       unevaluated
	 operand. Equivalent to

	 construct<T1, T2, T1, T2>(p, std::forward<NonPair>(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 con-
       struction

Return value
	  (none)

Notes
	  This function	is called (through std::allocator_traits) by any allo-
       cator-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
       behavior
			      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
       tuples 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		  2022.07.31	  std::scoped...::construct(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::scoped_allocator_adaptor::construct&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help