std::list::emplace(3)

💖 std::list::emplace(3) 💖

okay so bestie, welcome to the std::list::emplace(3) page from the C++ Standard Libary manual ✨ (yes, that’s the manual name, spelling and all — we’re not doing a vibe check on the source, periodt). This is the page for the list member that emplaces stuff. Let’s get into it 🫶.

---

🎀 NAME 🎀

std::list::emplace — std::list::emplace.

That’s it. That’s the name. No cap, it’s literally just the same thing twice 💅.

✨ Synopsis ✨

Available since C++11 🦋:

template< class... Args >
iterator emplace( const_iterator pos, Args&&... args );

Okay so what does it do? It inserts a new element into the container directly before pos 👑.

The element is constructed through std::allocator_traits::construct, which uses placement-new to construct the element in-place at a location provided by the container. The arguments args... are forwarded to the constructor as std::forward<Args>(args).... And bestie, args... may directly or indirectly refer to a value in the container — eye contact, this is important 👀.

No iterators or references are invalidated. Not me being obsessed with a function that doesn’t wreck your iterators 😭✨.

🌸 Parameters 🌸

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

🦋 Type requirements 🦋

• T (the container’s element type) must meet the requirements of EmplaceConstructible.

👑 Return value 👑

Iterator pointing to the emplaced element. That’s the whole return value, iconic behavior 💅.

⭐ Complexity ⭐

Constant. That’s it. Constant. Slay.

💀 Exceptions 💀

If an exception is thrown (e.g. by the constructor), the container is left unmodified, as if this function was never called — that’s the strong exception guarantee, bestie. So like, no half-built mess left behind, fr fr 🫶.

🍓 Example 🍓

Run this code:

// Run this code

#include <iostream>
#include <string>
#include <list>

struct A
{
    std::string s;

    A(std::string str) : s(std::move(str)) { std::cout << " constructed\n"; }

    A(const A& o) : s(o.s) { std::cout << " copy constructed\n"; }

    A(A&& o) : s(std::move(o.s)) { std::cout << " move constructed\n"; }

    A& operator=(const A& other)
    {
        s = other.s;
        std::cout << " copy assigned\n";
        return *this;
    }

    A& operator=(A&& other)
    {
        s = std::move(other.s);
        std::cout << " move assigned\n";
        return *this;
    }
};

int main()
{
    std::list<A> container;

    std::cout << "construct 2 times A:\n";
    A two { "two" };
    A three { "three" };

    std::cout << "emplace:\n";
    container.emplace(container.end(), "one");

    std::cout << "emplace with A&:\n";
    container.emplace(container.end(), two);

    std::cout << "emplace with A&&:\n";
    container.emplace(container.end(), std::move(three));

    std::cout << "content:\n";
    for (const auto& obj : container)
        std::cout << ' ' << obj.s;
    std::cout << '\n';
}

🌈 Output 🌈

construct 2 times A:
 constructed
 constructed
emplace:
 constructed
emplace with A&:
 copy constructed
emplace with A&&:
 move constructed
content:
 one two three

💅 Defect reports 💅

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• DR LWG 2164 — applied to C++11; behavior as published: it was not clear whether the arguments can refer to the container; correct behavior: clarified.

👀 See also 👀

• insert — inserts elements (public member function).
• emplace_back — constructs an element in-place at the end (C++11) (public member function).

---

kisses 💖 this page was served from http://cppreference.com, dated 2024.06.10, and it’s literally std::list::emplace(3) — bye bestie, go emplace something cute 🎀🦋