FreeBSD Manual Pages
std::vector::emplace(3) C++ Standard Libary std::vector::emplace(3) NAME std::vector::emplace - std::vector::emplace Synopsis template< class... Args > (since C++11) iterator emplace( const_iterator pos, Args&&... args ); (until C++20) template< class... Args > (since C++20) constexpr 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 re- fer to a value in the container. If the new size() is greater than capacity(), all iterators and ref- erences are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated. Parameters pos - iterator before which the new element will be constructed args - arguments to forward to the constructor of the element Type requirements - T (the container's element type) must meet the requirements of Move- Assignable, MoveInsertable and EmplaceConstructible. Return value Iterator pointing to the emplaced element. Complexity Linear in the distance between pos and end of the container. Exceptions If an exception is thrown other than by the copy constructor, move constructor, assignment operator, or move assignment operator of the value type, or if an exception is thrown while emplace is used to insert a single element at the end and the value type is either CopyInsertable or nothrow move con- structible, there are no effects (strong exception guarantee). Otherwise, the effects are unspecified. Example // Run this code #include <iostream> #include <string> #include <vector> struct A { std::string s; A(std::string str) : s(std::move(str)) { std::cout << " con- structed\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 Defect reports The following behavior-changing defect reports were applied retroac- tively to previously published C++ standards. DR Applied to Behavior as published Correct behavior LWG 2164 C++11 it was not clear whether the arguments can clarified refer to the container See also insert inserts elements (public member function) emplace_back constructs an element in-place at the end (C++11) (public member function) http://cppreference.com 2022.07.31 std::vector::emplace(3)
NAME | Synopsis | Parameters | Type requirements | Return value | Complexity | Exceptions | Example | Output: | See also
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::vector::emplace&sektion=3&manpath=FreeBSD+Ports+15.0>