std::vector<T,Allocator>::emplace (3) - Linux Man Pages

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

NAME

std::vector<T,Allocator>::emplace - std::vector<T,Allocator>::emplace

Synopsis


template< class... Args > (since C++11)
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. The arguments args... are forwarded to the constructor as std::forward<Args>(args)....
If the new size() is greater than capacity(), all iterators and references 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 MoveAssignable, 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 constructible, there are no effects (strong exception guarantee).
Otherwise, the effects are unspecified.

Notes


The specialization std::vector<bool> did not have emplace() member until C++14.

See also


       inserts elements
insert (public member function)