std::destroy_n

From cppreference.com

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros(C++20)
Language support library
Concepts library(C++20)
Diagnostics library
Memory management library
Metaprogramming library(C++11)
General utilities library
Containers library
Iterators library
Ranges library(C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library(C++17)
Concurrency support library(C++11)
Execution control library(C++26)
Technical specifications
Symbols index
External libraries

[edit]

Memory management library

voidify

(exposition only*)

Allocators

allocator
allocator_traits (C++11)
allocation_result (C++23)
scoped_allocator_adaptor (C++11)
pmr::polymorphic_allocator (C++17)

allocator_arg (C++11)
uses_allocator (C++11)
uses_allocator_construction_args (C++20)
make_obj_using_allocator (C++20)
uninitialized_construct_using_allocator (C++20)

Uninitialized memory algorithms

uninitialized_copy
uninitialized_fill
uninitialized_move (C++17)
uninitialized_copy_n (C++11)
uninitialized_fill_n
uninitialized_move_n (C++17)
construct_at (C++20)

uninitialized_default_construct (C++17)
uninitialized_value_construct (C++17)
destroy (C++17)
uninitialized_default_construct_n (C++17)
uninitialized_value_construct_n (C++17)
destroy_n (C++17)
destroy_at (C++17)

Constrained uninitialized memory algorithms

ranges::uninitialized_copy (C++20)
ranges::uninitialized_fill (C++20)
ranges::uninitialized_move (C++20)
ranges::uninitialized_copy_n (C++20)
ranges::uninitialized_fill_n (C++20)
ranges::uninitialized_move_n (C++20)
ranges::construct_at (C++20)

ranges::uninitialized_default_construct (C++20)
ranges::uninitialized_value_construct (C++20)
ranges::destroy (C++20)
ranges::uninitialized_default_construct_n (C++20)
ranges::uninitialized_value_construct_n (C++20)
ranges::destroy_n (C++20)
ranges::destroy_at (C++20)

Memory resources

pmr::memory_resource (C++17)
pmr::get_default_resource (C++17)
pmr::set_default_resource (C++17)
pmr::new_delete_resource (C++17)
pmr::pool_options (C++17)

pmr::null_memory_resource (C++17)
pmr::synchronized_pool_resource (C++17)
pmr::unsynchronized_pool_resource (C++17)
pmr::monotonic_buffer_resource (C++17)

Explicit lifetime management
start_lifetime_as (C++23)
start_lifetime_as_array (C++23)

Types for composite class design
indirect (C++26)
polymorphic (C++26)

Uninitialized storage(until C++20)

raw_storage_iterator (until C++20*)
get_temporary_buffer (until C++20*)

return_temporary_buffer (until C++20*)

Garbage collector support(until C++23)

declare_reachable (C++11)(until C++23)
declare_no_pointers (C++11)(until C++23)
pointer_safety (C++11)(until C++23)

undeclare_reachable (C++11)(until C++23)
undeclare_no_pointers (C++11)(until C++23)
get_pointer_safety (C++11)(until C++23)

Low level memory
management

operator newoperator new[]

operator deleteoperator delete[]

(C++11)

(C++11)

(C++17)

(C++20)

(C++17)

(C++11)

(C++11)

(C++11)

(until C++17*)

(C++11)

(C++17)

(C++26)

(C++26)

enable_shared_from_this

(C++11)

(C++11)

(C++11)

(C++23)

(C++23)

(C++11)

(C++20)

(C++11)

(C++11)

(C++20)

is_sufficiently_aligned

(C++26)

C Library

malloc
calloc
realloc

free
aligned_alloc (C++17)

[edit]

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

1) Destroys then objects in the range starting atfirst, as if by

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

2) Same as(1), but executed according topolicy. This overload participates in overload resolution only if all following conditions are satisfied:

std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> istrue.	(until C++20)
std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>> istrue.	(since C++20)

[edit]Parameters

first	-	the beginning of the range of elements to destroy
n	-	the number of elements to destroy
policy	-	theexecution policy to use
Type requirements
- `ForwardIt` must meet the requirements ofLegacyForwardIterator.
- No increment, assignment, comparison, or indirection through valid instances of`ForwardIt` may throw exceptions.

[edit]Return value

The end of the range of objects that has been destroyed (i.e.,std::next(first, n)).

[edit]Complexity

Linear inn.

[edit]Exceptions

The overload with a template parameter namedExecutionPolicy reports errors as follows:

If execution of a function invoked as part of the algorithm throws an exception andExecutionPolicy is one of thestandard policies,std::terminate is called. For any otherExecutionPolicy, the behavior is implementation-defined.
If the algorithm fails to allocate memory,std::bad_alloc is thrown.

[edit]Possible implementation

template<class ForwardIt,class Size>constexpr// since C++20ForwardIt destroy_n(ForwardIt first, Size n){for(; n>0;(void)++first,--n)std::destroy_at(std::addressof(*first));return first;}

[edit]Example

The following example demonstrates how to usedestroy_n to destroy a contiguous sequence of elements.

Run this code

#include <iostream>#include <memory>#include <new> struct Tracer{int value;    ~Tracer(){std::cout<< value<<" destructed\n";}}; int main(){    alignas(Tracer)unsignedchar buffer[sizeof(Tracer)*8]; for(int i=0; i!=8;++i)        new(buffer+ sizeof(Tracer)* i) Tracer{i};// manually construct objects auto ptr=std::launder(reinterpret_cast<Tracer*>(buffer));     std::destroy_n(ptr,8);}

Output:

0 destructed1 destructed2 destructed3 destructed4 destructed5 destructed6 destructed7 destructed

[edit]See also

destroy (C++17)	destroys a range of objects (function template)[edit]
destroy_at (C++17)	destroys an object at a given address (function template)[edit]
ranges::destroy_n (C++20)	destroys a number of objects in a range (algorithm function object)[edit]