std::forwar...insert_after(3)

✨ std::forward_list::insert_after ✨

okay bestie so listen — this is a page from the C++ Standard Library manual (section 3, mwah), and it's all about std::forward_list::insert_after. Like the name literally says: you insert stuff after a position. No insert_before girlies here, forward_list only goes one way and we respect it 💅

---

🌸 SYNOPSIS 🌸

iterator insert_after( const_iterator pos, const T& value );

(1) (since C++11)

iterator insert_after( const_iterator pos, T&& value );

(2) (since C++11)

iterator insert_after( const_iterator pos, size_type count, const T& value );

(3) (since C++11)

template< class InputIt >
iterator insert_after( const_iterator pos, InputIt first, InputIt last );

(4) (since C++11)

iterator insert_after( const_iterator pos, std::initializer_list<T> ilist );

(5) (since C++11)

---

🦋 DESCRIPTION 🦋

The whole vibe: inserts elements after the specified position in the container. That's it, that's the job, and she ate 🔥

• 1,2) — inserts value after the element pointed to by pos.
• 3) — inserts count copies of the value after the element pointed to by pos.
• 4) — inserts elements from the range [first, last) after the element pointed to by pos. ⚠️ The behavior is undefined if first and last are iterators into *this. Like fr fr do NOT do that, that's undefined behavior territory and we don't go there 🙈
• 5) — inserts elements from initializer list ilist.

No iterators or references are invalidated. Not a single one. she's careful like that 🎀

---

💖 PARAMETERS 💖

• pos — iterator after which the content will be inserted
• value — element value to insert
• count — number of copies to insert
• first, last — the range of elements to insert
• ilist — initializer list to insert the values from

---

⭐ TYPE REQUIREMENTS ⭐

• InputIt must meet the requirements of LegacyInputIterator. (iykyk 👑)

---

🌈 RETURN VALUE 🌈

• 1,2) — iterator to the inserted element.
• 3) — iterator to the last element inserted, or pos if count == 0.
• 4) — iterator to the last element inserted, or pos if first == last.
• 5) — iterator to the last element inserted, or pos if ilist is empty.

like she always gives you something back, even when nothing got inserted. main character energy 💅

---

🧚 EXCEPTIONS 🧚

If an exception is thrown for any reason, these functions have no effect — that's the strong exception safety guarantee. lowkey iconic, she cleans up after herself ✨

---

🍓 COMPLEXITY 🍓

• 1,2) — Constant.
• 3) — Linear in count.
• 4) — Linear in std::distance(first, last).
• 5) — Linear in ilist.size().

---

💜 EXAMPLE 💜

// Run this code

#include <forward_list>
#include <iostream>
#include <string>
#include <vector>

void print(const std::forward_list<int>& list)
{
    std::cout << "list: {";
    for (char comma[3] = {'\0', ' ', '\0'}; int i : list)
    {
        std::cout << comma << i;
        comma[0] = ',';
    }
    std::cout << "}\n";
}

int main()
{
    std::forward_list<int> ints{1, 2, 3, 4, 5};
    print(ints);

    // insert_after (2)
    auto beginIt = ints.begin();
    ints.insert_after(beginIt, -6);
    print(ints);

    // insert_after (3)
    auto anotherIt = beginIt;
    ++anotherIt;
    anotherIt = ints.insert_after(anotherIt, 2, -7);
    print(ints);

    // insert_after (4)
    const std::vector<int> v = {-8, -9, -10};
    anotherIt = ints.insert_after(anotherIt, v.cbegin(), v.cend());
    print(ints);

    // insert_after (5)
    ints.insert_after(anotherIt, {-11, -12, -13, -14});
    print(ints);
}

🫶 Output 🫶

list: {1, 2, 3, 4, 5}
list: {1, -6, 2, 3, 4, 5}
list: {1, -6, -7, -7, 2, 3, 4, 5}
list: {1, -6, -7, -7, -8, -9, -10, 2, 3, 4, 5}
list: {1, -6, -7, -7, -8, -9, -10, -11, -12, -13, -14, 2, 3, 4, 5}

look at all those negative numbers sliding in. obsessed 😭🔥

---

🎀 SEE ALSO 🎀

• emplace_after — constructs elements in-place after an element (public member function)
• push_front — inserts an element to the beginning (public member function)

---

okay that's the whole page bestie, go forth and insert after 💖

source/version: http://cppreference.com, dated 2024.06.10 — and this beauty is std::forwar...insert_after(3) (yes the title got cut off in the manual header, we don't know her full name either, it's giving mysterious 🌸). mwah, bye! 💅✨