(C++17) | ||||
| Sequence | ||||
(C++11) | ||||
(C++26) | ||||
(C++26) | ||||
(C++11) | ||||
| Associative | ||||
| Unordered associative | ||||
(C++11) | ||||
(C++11) | ||||
(C++11) | ||||
(C++11) | ||||
| Adaptors | ||||
(C++23) | ||||
(C++23) | ||||
(C++23) | ||||
(C++23) | ||||
| Views | ||||
(C++20) | ||||
(C++23) | ||||
| Tables | ||||
| Iterator invalidation | ||||
| Member function table | ||||
| Non-member function table |
| Member functions | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Non-member functions | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Deduction guides(C++17) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
template<class...Args> iterator emplace( const_iterator pos, Args&&...args); | (since C++11) (constexpr since C++26) | |
Inserts a new element into the container directly beforepos.
The element is constructed throughstd::allocator_traits::construct, which uses placementnew to construct the element in-place at a location provided by the container.
The argumentsargs... are forwarded to the constructor asstd::forward<Args>(args)....args... may directly or indirectly refer to a value in the container.
No iterators or references are invalidated.
Contents |
| pos | - | iterator before which the new element will be constructed |
| args | - | arguments to forward to the constructor of the element |
| Type requirements | ||
-IfT is notEmplaceConstructible intolist fromargs...., the behavior is undefined | ||
Iterator pointing to the emplaced element.
Constant.
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).
#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(constauto& obj: container)std::cout<<' '<< obj.s;std::cout<<'\n';}
Output:
construct 2 times A: constructed constructedemplace: constructedemplace with A&: copy constructedemplace with A&&: move constructedcontent: one two three
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 unclear whether the arguments can refer to the container | made clear |
| inserts elements (public member function)[edit] | |
(C++11) | constructs an element in-place at the end (public member function)[edit] |
