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

NAME
     std::uninitialized_value_construct - std::uninitialized_value_construct

Synopsis
	Defined in header <memory>
	template< class ForwardIt >
	void  uninitialized_value_construct(  ForwardIt first, ForwardIt     (1)
     (since C++17)
	last );
	template< class ExecutionPolicy, class ForwardIt >

	void uninitialized_value_construct( ExecutionPolicy&&  policy,	     (2)
     (since C++17)

					    ForwardIt first, ForwardIt
	last );

	1)    Constructs   objects   of   type	 typename   iterator_traits<For-
     wardIt>::value_type in the
	uninitialized storage designated by the range [first,  last)  by  value-
     initialization,
	as if by for (; first != last; ++first)
	    ::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, last	     -	       the range of the elements to initialize
	policy		      - 	 the execution policy to use. See execu-
     tion 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
	(none)

Complexity
	Linear in the distance between first and last.

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>
	void uninitialized_value_construct(ForwardIt first, ForwardIt last)
	{
	    using Value = typename std::iterator_traits<ForwardIt>::value_type;
	    ForwardIt current = first;
	    try
	    {
		for (; current != last; ++current)
		    ::new (const_cast<void*>(static_cast<const volatile void*>(
			std::addressof(*current)))) Value();
	    }
	    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{first + n};

	      std::uninitialized_value_construct(first, last);

	      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
	  // zero-fills 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(std::begin(v), std::end(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 in
	uninitialized_value_construct_n       an uninitialized area  of  memory,
     defined by a
	(C++17) 			      start and a count
					      (function template)
					      constructs objects by default-ini-
     tialization
	uninitialized_default_construct        in  an uninitialized area of mem-
     ory, defined by
	(C++17) 			      a range
					      (function template)
					      constructs objects  by  value-ini-
     tialization in
	ranges::uninitialized_value_construct  an  uninitialized area of memory,
     defined by a
	(C++20) 			      range
					      (niebloid)

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