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

FreeBSD Manual Pages

  
 
  

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 al-
       ready constructed
	  are destroyed	in an unspecified order.
	  2) Same as (1), but executed according to policy. This overload par-
       ticipates 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 initial-
       ize
	  policy	       -	 the execution policy to use. See exe-
       cution policy for
					 details.

Type requirements
	  -
	  ForwardIt must meet the requirements of LegacyForwardIterator.
	  -
	  No  increment,  assignment, comparison, or indirection through valid
       instances 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
       errors 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::termi-
       nate is called.
	      For  any	other ExecutionPolicy, the behavior is implementation-
       defined.
	    * 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<For-
       wardIt>::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_con-
       struct
	    // 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
       Correct behavior
	  LWG  3870  C++20	this algorithm might create objects on a const
       kept disallowed
			      storage

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

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

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

home | help