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)
										 (un-
       til C++20)
	     const_cast<void*>(static_cast<const		      volatile
       (since C++20)
	     void*>(std::addressof(e)))

	  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 does
       not participate
	  in overload resolution unless
	  std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>
	  (until C++20)
	  std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>
	  (since C++20)	is true.

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 ex-
       ecution 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 (const_cast<void*>(static_cast<const volatile void*>(
		       std::addressof(*current)))) T(*first);
	       }
	       return current;
	   } catch (...) {
	       for (; d_first != current; ++d_first) {
		   d_first->~T();
	       }
	       throw;
	   } }

Example
       // Run this code

	#include <iostream>
	#include <memory>
	#include <cstdlib>
	#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_

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		  2022.07.31	    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.0>

home | help