◐ Shell
clean mode source ↗

std::ranges::destroy - cppreference.com

From cppreference.com

Defined in header <memory>

Call signature

 
template< /*nothrow-input-iterator*/ I, /*nothrow-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< /*nothrow-input-range*/ R >
    requires std::destructible<ranges::range_value_t<R>>
constexpr ranges::borrowed_iterator_t<R> destroy( R&& r ) noexcept;
(2) (since C++20) 
template< /*execution-policy*/ Ep, /*nothrow-random-access-iterator*/ I,
          /*nothrow-sized-sentinel-for*/<I> S >
    requires std::destructible<std::iter_value_t<I>>
I destroy( Ep&& policy, I first, S last );
(3) (since C++26) 
template< /*execution-policy*/ Ep, /*nothrow-sized-random-access-range*/ R >
    requires std::destructible<ranges::range_value_t<R>>
ranges::borrowed_iterator_t<R> destroy( Ep&& policy, R&& r );
(4) (since C++26)

For the definition of /*execution-policy*/, see this page; for the definition of other exposition-only concepts, see this page.

1) Destroys elements in the target 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 target range.

3,4) Same as (1,2), but executed according to policy.

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

Parameters

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

Return value

As described above.

Exceptions

3,4) During the execution process:

  • If the temporary memory resources required for parallelization are not available, std::bad_alloc is thrown.
  • If an uncaught exception is thrown while accessing objects via an algorithm argument, the behavior is determined by the execution policy (for standard policies, std::terminate is invoked).

Notes

Feature-test macro Value Std Feature
__cpp_lib_parallel_algorithm 202506L (C++26) Parallel range algorithms

Possible implementation

struct destroy_fn
{
    template</*nothrow-input-iterator*/ I, /*nothrow-sentinel-for*/<I> S>
        requires std::destructible<std::iter_value_t<I>>
    constexpr I operator()(I first, S last) const noexcept
    {
        for (; first != last; ++first)
            ranges::destroy_at(std::addressof(*first));
        return first;
    }
    
    template</*nothrow-input-range*/ R>
        requires std::destructible<ranges::range_value_t<R>>
    constexpr ranges::borrowed_iterator_t<R> operator()(R&& r) const noexcept
    {
        return (*this)(ranges::begin(r), ranges::end(r));
    }
    
    template</*nothrow-forward-range*/ R>
        requires std::destructible<ranges::range_value_t<R>>
    constexpr ranges::borrowed_iterator_t<R> operator()(R&& r) const noexcept
    {
        return (*this)(ranges::begin(r),
                       ranges::next(ranges::begin(r), ranges::end(r)));
    }
};

inline constexpr destroy_fn destroy{};

Example

Demonstrates how to use ranges::destroy to destroy a contiguous sequence of elements.

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

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

int main()
{
    alignas(Tracer) unsigned char buffer[sizeof(Tracer) * 4];
    
    for (int i = 0; i < 4; ++i)
        new (buffer + sizeof(Tracer) * i) Tracer{i}; // manually construct objects

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

    std::ranges::destroy(ptr, ptr + 4);
}

Output: 

0 destructed
1 destructed
2 destructed
3 destructed

See also