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

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

(начиная с C++11)

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

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

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

Итераторы и ссылки не инвалидируются.

Параметры

pos	-	итератор, перед которым будет сконструирован новый элемент
args	-	аргументы, передаваемые конструктору элемента
Требования к типам
-`T` должен соответствовать требованиям 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++.

Отчет об ошибке	Применяется к	Опубликованное поведение	Корректное поведение
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/cpp/container/list/emplace