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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::uninitialized_fill_n - std::uninitialized_fill_n

Synopsis
	  Defined in header <memory>
	  template< class ForwardIt, class Size, class T >
	  ForwardIt  uninitialized_fill_n(  ForwardIt first, Size count, const
       (1)
	  T& value );
	  template< class ExecutionPolicy, class ForwardIt, class Size,
	  class	T >

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

					  ForwardIt first, Size	count, const
	  T& value );

	  1)  Copies  the  given value value to	the first count	elements in an
       uninitialized
	  memory area beginning	at first as if by for (; n--; ++first)
	      ::new (/*	VOIDIFY	*/(*first))
		  typename std::iterator_traits<ForwardIt>::value_type(value);
	  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.
	  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
				       initialize
	  count		   -	       number of elements to construct
	  value		    -		 the  value  to	construct the elements
       with

Type requirements
	  -
	  ForwardIt must meet the requirements of LegacyForwardIterator.
	  -
	  No increment,	assignment, comparison,	or indirection	through	 valid
       instances of
	  ForwardIt may	throw exceptions.
	  Applying  &*	to a ForwardIt 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 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 ForwardIt, class Size,	class T>
	  ForwardIt uninitialized_fill_n(ForwardIt first, Size count, const T&
       value)
	  {
	      using V =	typename std::iterator_traits<ForwardIt>::value_type;
	      ForwardIt	current	= first;
	      try
	      {
		  for (; count > 0; ++current, (void) --count)
		      ::new	(static_cast<void*>(std::addressof(*current)))
       V(value);
		  return current;
	      }
	      catch (...)
	      {
		  for (; first != current; ++first)
		      first->~V();
		  throw;
	      }
	  }

Example
       // Run this code

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

	int main()
	{
	    std::string* p;
	    std::size_t	sz;
	    std::tie(p,	sz) = std::get_temporary_buffer<std::string>(4);
	    std::uninitialized_fill_n(p, sz, "Example");

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

Output:
Example
Example
Example
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 ForwardIt,
	  LWG  866   C++98	 if					  uses
       global replacement-
			      T::operator  new exists, the program     new in-
       stead
			      might be ill-formed
			      the location of the first	element
	  LWG 1339 C++98      following				      returned
			      the filling range	was not	returned
	  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
				       copies an object	 to  an	 uninitialized
       area of memory,
	  uninitialized_fill	       defined by a range
				       (function template)
	  ranges::uninitialized_fill_n	copies	an  object to an uninitialized
       area of memory,
	  (C++20)		       defined by a start and a	count
				       (niebloid)

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

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

home | help