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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::destroy - std::destroy

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

	  1) Destroys the objects in the range [first, last), as if by

	for (; first !=	last; ++first)
	  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, last	       -	 the range of elements to destroy
	  policy	       -	 the execution policy to use. See exe-
       cution 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
	  (none)

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 ForwardIt >
	  constexpr // since C++20
	  void destroy(	ForwardIt first, ForwardIt last	)
	  {
	    for	(; first != last; ++first)
	      std::destroy_at(std::addressof(*first));
	  }

Example
	  The  following  example demonstrates how to use destroy 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(ptr, ptr + 8);
	}

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

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

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

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

home | help