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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::destroy_n -	std::destroy_n

Synopsis
	  Defined in header <memory>
	  template<	  class	      ForwardIt,       class	   Size	     >
       (since C++17)
	  ForwardIt    destroy_n(    ForwardIt	  first,     Size     n	    );
       (until C++20)
	  template<	  class	      ForwardIt,       class	   Size	     >
       (since C++20)
	  constexpr ForwardIt destroy_n( ForwardIt first, Size n );	 (1)
	  template< class ExecutionPolicy, class ForwardIt, class Size >
	  ForwardIt    destroy_n(    ExecutionPolicy&&	  policy,    ForwardIt
       (2) (since C++17)
	  first, Size n	);

	  1) Destroys the n objects in the range starting at first, as if by

	for (; n > 0; (void) ++first, --n)
	  std::destroy_at(std::addressof(*first));

	  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		     -		the beginning of the range of elements
       to destroy
	  n		    -	       the number of elements to destroy
	  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	that has been destroyed	(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>
	  constexpr // since C++20
	  ForwardIt destroy_n( ForwardIt first,	Size n )
	  {
	    for	(; n > 0; (void) ++first, --n)
	      std::destroy_at(std::addressof(*first));
	    return first;
	  }

Example
	  The following	example	demonstrates how to use	destroy_n to destroy a
       contiguous
	  sequence of elements.

       // Run this code

	#include <memory>
	#include <new>
	#include <iostream>

	struct Tracer {
	    int	value;
	    ~Tracer() {	std::cout << value << "	destructed\n"; }
	};

	int main()
	{
	    alignas(Tracer) unsigned char buffer[sizeof(Tracer)	* 8];

	    for	(int i = 0; i <	8; ++i)
		new(buffer  +  sizeof(Tracer)  * i) Tracer{i}; //manually con-
       struct objects

	    auto ptr = std::launder(reinterpret_cast<Tracer*>(buffer));

	    std::destroy_n(ptr,	8);
	}

Output:
	0 destructed
	1 destructed
	2 destructed
	3 destructed
	4 destructed
	5 destructed
	6 destructed
	7 destructed

See also
	  destroy	    destroys a range of	objects
	  (C++17)	    (function template)
	  destroy_at	    destroys an	object at a given address
	  (C++17)	    (function template)
	  ranges::destroy_n destroys a number of objects in a range
	  (C++20)	    (niebloid)

http://cppreference.com		  2022.07.31		     std::destroy_n(3)

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

home | help