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

FreeBSD Manual Pages

  
 
  

home | help 
std::uninitialized_copy(3)    C++ Standard Libary   std::uninitialized_copy(3)

NAME
       std::uninitialized_copy - std::uninitialized_copy

Synopsis
	  Defined in header <memory>
	  template< class InputIt, class NoThrowForwardIt >

	  NoThrowForwardIt  uninitialized_copy(	 InputIt  first, InputIt last,
       (1)

					       NoThrowForwardIt	d_first	);
	  template< class ExecutionPolicy, class ForwardIt, class
	  NoThrowForwardIt >

	  NoThrowForwardIt   uninitialized_copy(   ExecutionPolicy&&   policy,
       (2) (since C++17)
					       ForwardIt first,	ForwardIt
	  last,

					       NoThrowForwardIt	d_first	);

	  1)  Copies elements from the range [first, last) to an uninitialized
       memory area
	  beginning at d_first as if by	 for  (;  first	 !=  last;  ++d_first,
       (void) ++first)
	      ::new (/*	VOIDIFY	*/(*d_first))
		  typename		      std::iterator_traits<NoThrowFor-
       wardIt>::value_type(*first);
	  where	/* VOIDIFY */(e) is:

	  static_cast<void*>(&e)		(until C++11)
	  static_cast<void*>(std::addressof(e))	(since C++11)

	  If an	exception is thrown during the initialization, the objects al-
       ready constructed
	  are destroyed	in an unspecified order.

	  If  d_first  +  [0,  std::distance(first,   last))   overlaps	  with
       (since C++20)
	  [first, last), the behavior is undefined.

	  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 copy
	  d_first		 -	   the	beginning  of  the destination
       range
	  policy		-	 the execution policy to use. See exe-
       cution policy for
					 details.

Type requirements
	  -
	  InputIt must meet the	requirements of	LegacyInputIterator.
	  -
	  ForwardIt must meet the requirements of LegacyForwardIterator.
	  -
	  NoThrowForwardIt must	meet the requirements  of  LegacyForwardItera-
       tor.
	  -
	  No  increment,  assignment, comparison, or indirection through valid
       instances of
	  NoThrowForwardIt may throw exceptions.
	  Applying &* to a NoThrowForwardIt value must yield a pointer to  its
       value type.
	  (until C++11)

Return value
	  Iterator to the element past the last	element	copied.

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 InputIt, class NoThrowForwardIt> NoThrowForwardIt	unini-
       tialized_copy(InputIt first, InputIt last, NoThrowForwardIt d_first) {
	   using     T	   =	 typename     std::iterator_traits<NoThrowFor-
       wardIt>::value_type;
	   NoThrowForwardIt current = d_first;
	   try
	   {
	       for (; first != last; ++first, (void) ++current)
		   ::new	(static_cast<void*>(std::addressof(*current)))
       T(*first);
	       return current;
	   }
	   catch (...)
	   {
	       for (; d_first != current; ++d_first)
		   d_first->~T();
	       throw;
	   } }

Example
       // Run this code

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

	int main()
	{
	    const char *v[] = {"This", "is", "an", "example"};

	    auto sz = std::size(v);

	    if	 (void	 *pbuf	 =    std::aligned_alloc(alignof(std::string),
       sizeof(std::string) * sz))
	    {
		try
		{
		    auto first = static_cast<std::string*>(pbuf);
		    auto    last    =	std::uninitialized_copy(std::begin(v),
       std::end(v), first);

		    for	(auto it = first; it !=	last; ++it)
			std::cout << *it << '_';
		    std::cout << '\n';

		    std::destroy(first,	last);
		}
		catch (...) {}
		std::free(pbuf);
	    }
	}

Output:
	This_is_an_example_

	  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
			      given T as the value type	of
	  LWG 866   C++98	NoThrowForwardIt,  if			  uses
       global replacement-
			      T::operator  new exists, the program     new in-
       stead
			      might be ill-formed
			      the effect description used a for	loop
			      with the iteration		      discards
       the value
	  LWG 2133 C++98      expression ++d_first, ++first, which     of  one
       operand
			      results				       to dis-
       able that ADL
			      in an argument-dependent lookup of
			      operator,
	  LWG 2433 C++11      this algorithm might  be	hijacked  by	  uses
       std::addressof
			      overloaded operator&
	  LWG  3870  C++20	 this  algorithm might create objects on  kept
       disallowed
			      a	const storage

See also
	  uninitialized_copy_n	     copies a number of	objects	to  an	unini-
       tialized	area of
	  (C++11)		     memory
				     (function template)
	  ranges::uninitialized_copy  copies  a	 range of objects to an	unini-
       tialized	area of
	  (C++20)		     memory
				     (niebloid)

http://cppreference.com		  2024.06.10	    std::uninitialized_copy(3)

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

home | help