std::forwar..._range_after(3)

🌸 std::forward_list::insert_range_after 🌸

okay bestie, this is the std::forwar..._range_after(3) page from the C++ Standard Libary, and it's all about std::forward_list::insert_range_after. It's giving "new range-aware member function just dropped" energy, and honestly? We're obsessed. 💅

✨ NAME ✨

std::forward_list::insert_range_after — std::forward_list::insert_range_after

🫶 Synopsis 🫶

Since C++23, no cap. Signature:

template< container-compatible-range<T> R >
iterator insert_range_after( const_iterator pos, R&& rg );

It inserts, in non-reversing order, the copies of elements in rg before pos. Each iterator in the range rg is dereferenced exactly once. Literally once. ✨

pos must be any dereferenceable iterator in the range [begin(), end()) or the before_begin() iterator (thus, end() is not a valid argument for pos).

No iterators or references become invalidated. That's the good news, bestie. 🫶

The behavior is undefined if rg overlaps with the container. Like, do not do that. 😭

💅 Parameters 💅

• pos — an iterator after which the content will be inserted.
• rg — a container compatible range, that is, an input_range whose elements are convertible to T.

🌸 Type requirements 🌸

• T must be EmplaceConstructible into forward_list from *ranges::begin(rg). Otherwise, the behavior is undefined. 😭

🎀 Return value 🎀

An iterator that points at the copy of the last element inserted into forward_list or at pos if rg is empty.

🔥 Complexity 🔥

Linear in size of rg. Fr fr.

🦋 Notes 🦋

Feature-test macro vibe check:

• Feature-test macro: __cpp_lib_containers_ranges; Value: 202202L; Std: (C++23); Feature: Ranges-aware construction and insertion.

💖 Example 💖

// Run this code

#include <algorithm>
#include <cassert>
#include <forward_list>
#include <iterator>
#include <vector>

int main()
{
    auto container = std::forward_list{1, 2, 3, 4};
    auto pos = std::next(container.cbegin());
    assert(*pos == 2);
    const auto rg = std::vector{-1, -2, -3};

#ifdef __cpp_lib_containers_ranges
    container.insert_range_after(pos, rg);
#else
    container.insert_after(pos, rg.cbegin(), rg.cend());
#endif

    assert(std::ranges::equal(container, std::vector{1, 2, -1, -2, -3,
       3, 4}));
}

👑 See also 👑

• prepend_range — adds a range of elements to the beginning (C++23) (public member function).
• insert_after — inserts elements after an element (public member function).
• emplace_after — constructs elements in-place after an element (public member function).

---

source/version/date moment: this page lives at http://cppreference.com, dated 2024.06.10, and it's the std::forwar..._range_after(3) page. Bye bestie, go insert a range after something — or before pos, according to the lore — and slay 💖✨