template< class... Args >
iterator emplace( const_iterator pos, Args&&... args );
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.
T
is not EmplaceConstructible into vector
from args....T
is not MoveInsertable into vector
.T
is not MoveAssignable.Iterator pointing to the emplaced element.
[edit] ComplexityLinear in the distance between pos and end().
[edit] ExceptionsIf an exception is thrown other than by the copy constructor, move constructor, assignment operator, or move assignment operator of T
, or if an exception is thrown while emplace
is used to insert a single element at the end and T
is either CopyInsertable or nothrow move constructible, there are no effects (strong exception guarantee).
Otherwise, the effects are unspecified.
Example#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[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 unclear whether the arguments can refer to the container made clear [edit] See also inserts elementsRetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4