std::ranges::destroy_n(3)

✨ NAME ✨

okay so bestie, welcome to std::ranges::destroy_n(3) from the C++ Standard Libary (yes, "Libary" is literally how the header spells it — not me, I promise 😭). The NAME line is std::ranges::destroy_n — std::ranges::destroy_n, and the whole vibe is C++20 range cleanup: you give it a start iterator and a count, and it destroys those n objects like a responsible little destructor gremlin. 🧚💅

🌸 SYNOPSIS 🌸

Defined in header <memory>.

Call signature:

template< no-throw-input-iterator I >

    requires std::destructible<std::iter_value_t<I>>
(since C++20)

constexpr I destroy_n( I first, std::iter_difference_t<I> n )
noexcept;

It destroys the n objects in the range starting at first, and it's equivalent to:

return std::ranges::destroy(std::counted_iterator(first, n),
std::default_sentinel).base();

The function-like entities described on this page are 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.

In practice, they may be implemented as function objects, or with special compiler extensions.

🎀 PARAMETERS 🎀

• first — the beginning of the range of elements to destroy.
• n — the number of elements to destroy.

🦋 RETURN VALUE 🦋

The end of the range of objects that has been destroyed. You get an iterator back, bestie — closure, but make it C++. ✨

💅 COMPLEXITY 💅

Linear in n. No secret quadratic nonsense, no cap.

👑 POSSIBLE IMPLEMENTATION 👑

Here's the possible implementation, kept exact:

struct destroy_n_fn
{
    template<no-throw-input-iterator I>
        requires std::destructible<std::iter_value_t<I>>
    constexpr I operator()(I first, std::iter_difference_t<I> n)
const noexcept
    {
        for (; n != 0; (void)++first, --n)
            std::ranges::destroy_at(std::addressof(*first));
        return first;
    }
};

inline constexpr destroy_n_fn destroy_n{};

🌈 EXAMPLE 🌈

The following example demonstrates how to use ranges::destroy_n to destroy a contiguous sequence of elements.

The page says // Run this code — and here's the code:

#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) * 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_n(ptr, 8);
}

Output

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

⭐ SEE ALSO ⭐

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

---

okay bestie, that's the whole page. Source/version + date check: http://cppreference.com, 2024.06.10, page std::ranges::destroy_n(3). byeee 💖✨🫶