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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::uninitialized_default_construct_n	  -	std::uninitialized_de-
       fault_construct_n

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

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

						       ForwardIt first,	Size
	  n );

	  1)  Constructs  n objects of type typename std::iterator_traits<For-
       wardIt>::value_type
	  in the uninitialized storage starting	at first  by  default-initial-
       ization,	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 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		     -		the beginning of the range of elements
       to initialize
	  n		    -	       the number of elements to construct
	  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
       instances 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
       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, class Size>
	  ForwardIt uninitialized_default_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 <cstring>
	#include <iostream>
	#include <memory>
	#include <string>

	struct S
	{
	    std::string	m{"default value"};
	};

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

	    try
	    {
		auto first{reinterpret_cast<S*>(mem)};
		auto last = std::uninitialized_default_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_default_con-
       struct_n
	    // generally does not zero-initialize the given uninitialized mem-
       ory area.
	    int	v[]{1, 2, 3, 4};
	    const int original[]{1, 2, 3, 4};
	    std::uninitialized_default_construct_n(std::begin(v),
       std::size(v));

	    // An attempt to access v might be an undefined behavior,  pending
       CWG 1997:
	    // for (const int i	: v)
	    //	   std::cout <<	i << ' ';

	    // The result is unspecified:
	    std::cout  <<  (std::memcmp(v,  original, sizeof(v)) == 0 ?	"un" :
       "") << "modified\n";
	}

Possible output:
	default	value
	default	value
	default	value
	unmodified

	  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
	  uninitialized_default_construct	    default-initialization  in
       an uninitialized
	  (C++17)				    area of memory, defined by
       a range
						    (function template)
						    constructs	  objects   by
       value-initialization
	  uninitialized_value_construct_n	    in an  uninitialized  area
       of memory,
	  (C++17)				     defined  by a start and a
       count
						    (function template)
						    constructs objects by
	  ranges::uninitialized_default_construct_n default-initialization  in
       an uninitialized
	  (C++20)				    area of memory, defined by
       a start and
						    count
						    (niebloid)

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

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

home | help