std::ranges::destroy

 

C++

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

 

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[] nothrow_t nothrow new_handler set_new_handler get_new_handler (C++11) bad_alloc bad_array_new_length (C++11) align_val_t (C++17) destroying_delete_t (C++20) launder (C++17) Smart pointers unique_ptr (C++11) shared_ptr (C++11) weak_ptr (C++11) auto_ptr (until C++17*) owner_less (C++11) owner_less<void> (C++17) owner_hash (C++26) owner_equal (C++26) enable_shared_from_this (C++11) bad_weak_ptr (C++11) default_delete (C++11) out_ptr_t (C++23) inout_ptr_t (C++23) Miscellaneous pointer_traits (C++11) to_address (C++20) addressof (C++11) align (C++11) assume_aligned (C++20) is_sufficiently_aligned (C++26) C Library malloc calloc realloc free aligned_alloc (C++17)

 

Defined in header <memory>
Call signature
template<no-throw-input-iterator I, no-throw-sentinel-for<I> S >     requires std::destructible<std::iter_value_t<I>> constexpr I destroy( I first, S last )noexcept;	(1)	(since C++20)
template<no-throw-input-range R >     requires std::destructible<ranges::range_value_t<R>> constexprranges::borrowed_iterator_t<R> destroy( R&& r )noexcept;	(2)	(since C++20)

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

for(; first != last;++first) std::ranges::destroy_at(std::addressof(*first));return first;

2) Same as (1), but uses r as the source range, as if using ranges::begin(r) as first and ranges::end(r) as last.

The function-like entities described on this page are algorithm function objects (informally known as niebloids), that is:

• Explicit template argument lists cannot be specified when calling any of them.
• None of them are visible to argument-dependent lookup.
• When any of them are found by normal unqualified lookup as the name to the left of the function-call operator, argument-dependent lookup is inhibited.

Parameters

first, last	-	the iterator-sentinel pair defining the range of elements to destroy
r	-	the range to destroy

Return value

An iterator compares equal to last.

Complexity

Linear in the distance between first and last.

Possible implementation

struct destroy_fn {template<no-throw-input-iterator I, no-throw-sentinel-for<I> S> requires std::destructible<std::iter_value_t<I>>constexpr I operator()(I first, S last)constnoexcept{for(; first != last;++first) std::ranges::destroy_at(std::addressof(*first));return first;}   template<no-throw-input-range R> requires std::destructible<std::ranges::range_value_t<R>>constexpr std::ranges::borrowed_iterator_t<R> operator()(R&& r)constnoexcept{return operator()(std::ranges::begin(r), std::ranges::end(r));}};   inlineconstexpr destroy_fn destroy{};

Example

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

Output:

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

See also

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