std::forwar...place_after(3)

std::forwar...place_after(3) ✨

okay bestie, welcome to the C++ Standard Libary man page for std::forward_list::emplace_after (yes, that manual name is spelled “Libary” in the source, I’m not fixing it 💅). This is the one where you slide a brand-new element into a std::forward_list right after an iterator you already have. It’s giving “surgical insert, zero copies, main character energy.” 🦋

NAME 💖

std::forward_list::emplace_after — std::forward_list::emplace_after

Synopsis ✨

          template< class... Args >                                      (since
       C++11)
          iterator emplace_after( const_iterator pos, Args&&... args );

so this is a template, since C++11, that hands you back an iterator. no cap. 🫶

okay so what does it actually do? It inserts a new element into a position after the specified position in the container. The element is constructed in-place, i.e. no copy or move operations are performed. The constructor of the element is called with exactly the same arguments as supplied to the function.

and the best part? No iterators or references are invalidated. periodt. 💅

Parameters 🎀

• pos — iterator after which the new element will be constructed
• args — arguments to forward to the constructor of the element

Return value 🦋

Iterator to the new element. that’s the whole return value, bestie.

Complexity 🌸

Constant. literally constant — that’s it, that’s the complexity. 🫶

Exceptions 😭

If an exception is thrown for any reason, this function has no effect (strong exception safety guarantee). so if it goes off, it’s like it never happened. iconic behavior, honestly.

Example 🍓

The example demonstrates a canonical filling of a single-linked list in natural (as opposed to reverse) order.

// Run this code

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

        struct Sum
        {
            std::string remark;
            int sum;

            Sum(std::string remark, int sum)
                : remark{std::move(remark)}, sum{sum} {}

            void print() const
            {
                std::cout << remark << " = " << sum << '\n';
            }
        };

        int main()
        {
            std::forward_list<Sum> list;

            auto iter = list.before_begin();
            std::string str{"1"};

            for (int i{1}, sum{1}; i != 10; sum += i)
            {
                iter = list.emplace_after(iter, str, sum);
                ++i;
                str += " + " + std::to_string(i);
            }

            for (const Sum& s : list)
                s.print();
        }

Output:

1 = 1
1 + 2 = 3
1 + 2 + 3 = 6
1 + 2 + 3 + 4 = 10
1 + 2 + 3 + 4 + 5 = 15
1 + 2 + 3 + 4 + 5 + 6 = 21
1 + 2 + 3 + 4 + 5 + 6 + 7 = 28
1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 = 36
1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 = 45

See also 👑

• insert_after inserts elements after an element (public member function)

source/version/date sign-off, bestie: source is http://cppreference.com, version/date is 2024.06.10, and this page is std::forwar...place_after(3) — go slay your single-linked list 💖