std::vector::emplace(3)

💖 NAME 💖

std::vector::emplace(3) — yes bestie, that's the page, and the manual name up top is C++ Standard Libary (that's exactly how it's spelled here, and we love a typo moment 💀). The NAME line says std::vector::emplace - std::vector::emplace, which is giving “I am the moment” and honestly? iconic.

✨ Synopsis ✨

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

This has been a thing since C++11, and it's constexpr since C++20 💅.

It inserts a new element into the container directly before pos.

The element is constructed through std::allocator_traits::construct, which typically uses placement-new to construct the element in-place at a location provided by the container. However, if the required location has been occupied by an existing element, the inserted element is constructed at another location at first, and then move assigned into the required location.

The arguments args... are forwarded to the constructor as std::forward<Args>(args).... args... may directly or indirectly refer to a value in the container.

If after the operation the new size() is greater than old capacity() a reallocation takes place, in which case all iterators (including the end() iterator) and all references to the elements are invalidated. Otherwise, only the iterators and references before the insertion point remain valid.

🎀 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 MoveAssignable, MoveInsertable and EmplaceConstructible.

🌸 Return value 🌸

Iterator pointing to the emplaced element. Slay.

💅 Complexity 💅

Linear in the distance between pos and end of the container.

🫶 Exceptions 🫶

If an exception is thrown other than by the copy constructor, move constructor, assignment operator, or move assignment operator of the value type, or if an exception is thrown while emplace is used to insert a single element at the end and the value type is either CopyInsertable or nothrow move constructible, there are no effects (strong exception guarantee).

Otherwise, the effects are unspecified. 🙈

😭 Example 😭

The page says // Run this code, so here's the whole thing, no cap:

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

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::vector<A> container;
    // reserve enough place so vector does not have to resize
    container.reserve(10);
    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)

xoxo, bestie 💅 — source: http://cppreference.com, version/date: 2024.06.10, page: std::vector::emplace(3).