Inserts a new element into the container directly beforepos.

The element is constructed throughstd::allocator_traits::construct, which typically uses placementnew 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 argumentsargs... are forwarded to the constructor asstd::forward<Args>(args)....args... may directly or indirectly refer to a value in the container.

If after the operation the newsize() is greater than oldcapacity() a reallocation takes place, in which case all iterators (including theend() iterator) and all references to the elements are invalidated. Otherwise, only the iterators and references before the insertion point remain valid.

[edit]Parameters

[edit]Return value

Iterator pointing to the emplaced element.

[edit]Complexity

Linear in the distance betweenpos andend().

[edit]Exceptions

If an exception is thrown other than by the copy constructor, move constructor, assignment operator, or move assignment operator ofT, or if an exception is thrown whileemplace is used to insert a single element at the end andT is eitherCopyInsertable 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(constauto& obj: container)std::cout<<' '<< obj.s;std::cout<<'\n';}

construct 2 times A: constructed constructedemplace: constructedemplace with A&: copy constructedemplace with A&&: move constructedcontent: one two three

[edit]Defect reports

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

[edit]See also

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文