home | help 
std::uninit...construct_n(3)   C++ Standard Libary  std::uninit...construct_n(3)

NAME
     std::uninitialized_value_construct_n - std::uninitialized_value_construct_n

Synopsis
	Defined in header <memory>
	template< class ForwardIt, class Size >
	ForwardIt  uninitialized_value_construct_n(  ForwardIt first, Size n (1)
     (since C++17)
	);
	template< class ExecutionPolicy, class ForwardIt, class Size >

	ForwardIt uninitialized_value_construct_n( ExecutionPolicy&&
	policy, 							     (2)
     (since C++17)

						   ForwardIt first, Size n
	);

	1)   Constructs   n   objects	of  type  typename  iterator_traits<For-
     wardIt>::value_type in
	the uninitialized storage starting at first by value-initialization,  as
     if by for (;
	n > 0; (void) ++first, --n)
	    ::new (static_cast<void*>(std::addressof(*first)))
		typename std::iterator_traits<ForwardIt>::value_type();
	If an exception is thrown during the initialization, the objects already
     constructed
	are destroyed in an unspecified order.
	2) Same as (1), but executed according to policy. This overload partici-
     pates in
	overload resolution only if

	std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>    is    true.
     (until
										  C++20)
	std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>      is
     true. (since
										  C++20)

Parameters
	first		   -	       the beginning of the range of elements to
     initialize
	n		  -	     the number of elements to initialize
	policy		  -	     the execution policy to use. See  execution
     policy for
				     details.

Type requirements
	-
	ForwardIt must meet the requirements of LegacyForwardIterator.
	-
	No  increment,	assignment, comparison, or indirection through valid in-
     stances of
	ForwardIt may throw exceptions.

Return value
	The end of the range of objects (i.e., std::next(first, n)).

Complexity
	Linear in n.

Exceptions
	The overload with a template parameter named ExecutionPolicy reports er-
     rors as
	follows:

	  * If execution of a function invoked as part of the  algorithm  throws
     an exception
	    and  ExecutionPolicy is one of the standard policies, std::terminate
     is called.
	    For any other ExecutionPolicy, the	behavior  is  implementation-de-
     fined.
	  * If the algorithm fails to allocate memory, std::bad_alloc is thrown.

Possible implementation
	template<class ForwardIt, class Size>
	ForwardIt uninitialized_value_construct_n(ForwardIt first, Size n)
	{
	    using T = typename std::iterator_traits<ForwardIt>::value_type;
	    ForwardIt current = first;
	    try
	    {
		for (; n > 0 ; (void) ++current, --n)
		    ::new (const_cast<void*>(static_cast<const volatile void*>(
			std::addressof(*current)))) T();
		return current;
	    }
	    catch (...)
	    {
		std::destroy(first, current);
		throw;
	    }
	}

Example
     // Run this code

      #include <iostream>
      #include <memory>
      #include <string>

      int main()
      {
	  struct S { std::string m{"Default value"}; };

	  constexpr int n{3};
	  alignas(alignof(S)) unsigned char mem[n * sizeof(S)];

	  try
	  {
	      auto first{reinterpret_cast<S*>(mem)};
	      auto last = std::uninitialized_value_construct_n(first, n);

	      for (auto it{first}; it != last; ++it)
		  std::cout << it->m << '\n';

	      std::destroy(first, last);
	  }
	  catch (...)
	  {
	      std::cout << "Exception!\n";
	  }

	  // Notice that for "trivial types" the uninitialized_value_construct_n
	  // zero-initializes the given uninitialized memory area.
	  int v[]{1, 2, 3, 4};
	  for (const int i : v)
	      std::cout << i << ' ';
	  std::cout << '\n';
	  std::uninitialized_value_construct_n(std::begin(v), std::size(v));
	  for (const int i : v)
	      std::cout << i << ' ';
	  std::cout << '\n';
      }

Output:
      Default value
      Default value
      Default value
      1 2 3 4
      0 0 0 0

	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 3870 C++20	    this algorithm might create objects on a const  kept
     disallowed
			    storage

See also
						constructs objects by value-ini-
     tialization
	uninitialized_value_construct		in an uninitialized area of mem-
     ory, defined
	(C++17) 				by a range
						(function template)
						constructs objects  by	default-
     initialization
	uninitialized_default_construct_n	in an uninitialized area of mem-
     ory, defined
	(C++17) 				by a start and a count
						(function template)
						constructs objects by value-ini-
     tialization
	ranges::uninitialized_value_construct_n in an uninitialized area of mem-
     ory, defined
	(C++20) 				by a start and a count
						(niebloid)

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