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

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

(since C++11)

Вставляет новый элемент в контейнер непосредственно перед pos.

Элемент создается с помощью std::allocator_traits::construct, который использует placement-new для создания элемента на месте в позиции, предоставляемой контейнером.

Аргументы args... передаются конструктору как std::forward<Args>(args).... args... могут напрямую или косвенно ссылаться на значение в контейнере.

Никакие итераторы или ссылки не становятся недействительными.

Параметры

pos	-	итератор перед которым будет создан новый элемент
args	-	аргументы для передачи конструктору элемента
Требования к типу
-`T (the container's element type)` должен удовлетворять требованиям EmplaceConstructible.

Возвращаемое значение

Итератор, указывающий на помещенный элемент.

Сложность

Постоянная.

Исключения

Если возникает исключение (например, при вызове конструктора), контейнер остается неизменным, как если бы эта функция вообще не вызывалась (сильная гарантия исключения).

Пример

#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';
}

Вывод:

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

Отчеты об ошибках

Следующие отчеты об ошибках, изменяющие поведение, были применены ретроактивно к ранее опубликованным стандартам C++.

DR	Применен к	Поведение, как опубликовано	Корректное поведение
LWG 2164	C++11	не было ясно, могут ли аргументы ссылаться на контейнер	уточнено

См. также

insert	вставляет элементы (публичный член-функция)
emplace_back (C++11)	создает элемент на месте в конце (публичный член-функция)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/container/list/emplace