std::ranges::destroy

Определён в заголовочном файле `<memory>`
Сигнатура вызова
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)	(начиная с 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)	(начиная с 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)	(начиная с 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)	(начиная с C++26)

Определение /*execution-policy*/ см. на этой странице; определения других понятий, используемых только для описания, см. на этой странице.

1) Уничтожает элементы целевого диапазона [first, last) так, как если бы выполнялось

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

2) То же, что и (1), но в качестве целевого диапазона используется r.

3,4) То же, что и (1,2), но выполняется в соответствии с policy.

Функциональные объекты, описанные на этой странице, являются функциональными объектами алгоритмов (неофициально называемыми niebloids), то есть:

При вызове ни одного из них нельзя указать явный список аргументов шаблона.
Ни один из них не виден для поиска, зависящего от аргументов.
Если один из них найден при обычном неквалифицированном поиске в качестве имени слева от оператора вызова функции, поиск, зависящий от аргументов, блокируется.

Параметры

first, last	-	пара итератора и sentinel, задающая диапазон элементов для уничтожения
r	-	`range` для уничтожения
policy	-	политика выполнения

Возвращаемое значение

Как описано выше.

Исключения

3,4) Во время выполнения:

Если временные ресурсы памяти, необходимые для параллельного выполнения, недоступны, выбрасывается std::bad_alloc.
Если при доступе к объектам через аргумент алгоритма выбрасывается неперехваченное исключение, поведение определяется политикой выполнения (для стандартных политик вызывается std::terminate).

Примечания

Макрос проверки поддержки возможностей	Значение	Стандарт	Возможность
`__cpp_lib_parallel_algorithm`	`202506L`	(C++26)	Параллельные алгоритмы для диапазонов

Возможная реализация

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{};

Пример

Демонстрируется использование ranges::destroy для уничтожения непрерывной последовательности элементов.

#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);
}

Вывод:

0 destructed
1 destructed
2 destructed
3 destructed

См. также

ranges::destroy_n (C++20)	уничтожает заданное количество объектов в диапазоне (функциональный объект алгоритма)
ranges::destroy_at (C++20)	уничтожает объект по заданному адресу (функциональный объект алгоритма)
destroy (C++17)	уничтожает диапазон объектов (шаблон функции)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/memory/ranges/destroy