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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::uninitialized_copy_n - std::uninitialized_copy_n

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

	  NoThrowForwardIt  uninitialized_copy_n(  InputIt  first, Size	count,
       (1) (since C++11)

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

		    class Size,	class NoThrowForwardIt >
	  NoThrowForwardIt  uninitialized_copy_n(  ExecutionPolicy&&   policy,
       (2) (since C++17)
						 ForwardIt first, Size
	  count,

						 NoThrowForwardIt d_first );

	  1)  Copies  count  elements  from  a	range beginning	at first to an
       uninitialized memory
	  area beginning at d_first as if by
	  for (; n > 0;	++d_first, (void) ++first, --n)
	       ::new (static_cast<void*>(std::addressof(*d_first)))
		  typename		      std::iterator_traits<NoThrowFor-
       wardIt>::value_type(*first);
	  If an	exception is thrown during the initialization, the objects al-
       ready constructed
	  are destroyed	in an unspecified order.

	  If  d_first  +  [0, n) overlaps with first + [0, n), the behavior is
       (since C++20)
	  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		     -		the beginning of the range of the ele-
       ments to	copy
	  count		     -		the number of 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.

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

Complexity
	  Linear in count.

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

Example
       // Run this code

	#include <algorithm>
	#include <iostream>
	#include <memory>
	#include <string>
	#include <tuple>
	#include <vector>

	int main()
	{
	    std::vector<std::string> v = {"This", "is",	"an", "example"};

	    std::string* p;
	    std::size_t	sz;
	    std::tie(p,		   sz)		  =	       std::get_tempo-
       rary_buffer<std::string>(v.size());
	    sz = std::min(sz, v.size());

	    std::uninitialized_copy_n(v.begin(), sz, p);

	    for	(std::string* i	= p; i != p + sz; ++i)
	    {
		std::cout << *i	<< ' ';
		i->~basic_string<char>();
	    }
	    std::cout << '\n';

	    std::return_temporary_buffer(p);
	}

Possible 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
       Correct behavior
			      the effect description used a for	loop with
			      the				     iteration
       discards	the value
	  LWG  2133 C++98      expression ++d_first, ++first, --n, which    of
       one operand to
			      results
       disable those ADLs
			      in argument-dependent lookups 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 a
       kept disallowed
			      const storage

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

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

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

home | help