std::list::insert_range(3)

📦 version 2024.07.05, in nixpkgs unstable, opensuse-leap 16.0

okay so bestie 💅 welcome to std::list::insert_range(3) from the C++ Standard Libary — yes, that’s the manual name, and it is giving C++23 range-insertion excellence. This is the page for std::list::insert_range, and we’re gonna go through every lil detail together 🫶.

NAME

std::list::insert_range — std::list::insert_range (the name is literally the name, iconic 💖).

✨ Synopsis ✨

template< container-compatible-range<T> R >           (since C++23)
iterator insert_range( const_iterator pos, R&& rg );

okay so what does it do? It inserts, in non-reversing order, copies of elements in rg before pos 💅.

No iterators or references are invalidated — slay, nothing gets messed up ✨.

Each iterator in the range rg is dereferenced exactly once. Every. Single. One. No double-dipping 🍓.

behavior is undefined if rg overlaps with the container. like, do NOT do that, bestie 😭

Parameters

pos — iterator before which the content will be inserted (pos may be the end() iterator) 🎯
rg — a container compatible range, that is, an input_range whose elements are convertible to T 🧚

Type requirements

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

this is a hard requirement, no vibes-based workaround 🙈

Return value

An iterator that points at the copy of the first element inserted into list or at pos if rg is empty 👑.

Notes

Feature-test macro check ✅:

__cpp_lib_containers_ranges — value 202202L, std (C++23), feature: Ranges-aware construction and insertion 🌈

Example

example time, bestie 👇

       // Run this code

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

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

        #ifdef __cpp_lib_containers_ranges
            container.insert_range(pos, rg);
        #else
            container.insert(pos, rg.cbegin(), rg.cend());
        #endif
            assert(std::ranges::equal(container, std::list{1, 2, -1, -2, -3, 3,
       4}));
        }