Namespaces
Variants
Views
Actions

std::list<T,Allocator>::emplace

From cppreference.com
< cpp‎ | container‎ | list
 
 
 
 
template< class... Args >
iterator emplace( const_iterator pos, Args&&... args );
(since C++11)

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).... args... may directly or indirectly refer to a value in the container.

No iterators or references are invalidated.

Contents

[edit] 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.

[edit] Return value

Iterator pointing to the emplaced element.

[edit] Complexity

Constant.

[edit] Exceptions

If an exception is thrown (e.g. by the constructor), the container is left unmodified, as if this function was never called (strong exception guarantee).

Example

#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

[edit] Defect reports

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

DR Applied to Behavior as published Correct behavior
LWG 2164 C++11 it was not clear whether the arguments can refer to the container clarified

[edit] See also

inserts elements
(public member function) [edit]
constructs an element in-place at the end
(public member function) [edit]