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

From cppreference.com

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros(C++20)
Language support library
Concepts library(C++20)
Diagnostics library
Memory management library
Metaprogramming library(C++11)
General utilities library
Containers library
Iterators library
Ranges library(C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library(C++17)
Concurrency support library(C++11)
Execution control library(C++26)
Technical specifications
Symbols index
External libraries

[edit]

Containers library

node-handle (C++17)
Sequence
array (C++11)
vector
vector<bool>
inplace_vector (C++26)
hive (C++26)
deque
forward_list (C++11)
list
Associative
set
multiset
map
multimap
Unordered associative
unordered_set (C++11)
unordered_multiset (C++11)
unordered_map (C++11)
unordered_multimap (C++11)
Adaptors
stack
queue
priority_queue
flat_set (C++23)
flat_multiset (C++23)
flat_map (C++23)
flat_multimap (C++23)
Views
span (C++20)
mdspan (C++23)
Tables
Iterator invalidation
Member function table
Non-member function table

vector::vector
vector::~vector
vector::operator=
vector::assign
vector::assign_range (C++23)
vector::get_allocator
Element access
vector::operator[]
vector::at
vector::data
vector::front
vector::back
Iterators
vector::beginvector::cbegin (C++11)
vector::endvector::cend (C++11)
vector::rbeginvector::crbegin (C++11)
vector::rendvector::crend (C++11)

Capacity
vector::empty
vector::size
vector::max_size
vector::reserve
vector::capacity
vector::shrink_to_fit (DR*)
Modifiers
vector::clear
vector::erase
vector::insert
vector::insert_range (C++23)
vector::append_range (C++23)
vector::emplace (C++11)
vector::emplace_back (C++11)
vector::push_back
vector::pop_back
vector::resize
vector::swap

Non-member functions

operator==operator<=> (C++20)
swap(std::vector)
erase(std::vector)erase_if(std::vector) (C++20)(C++20)

operator!=operator<operator>operator<=operator>=

(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)

Deduction guides(C++17)

[edit]

template<class...Args> void emplace_back( Args&&...args);		(until C++17)
template<class...Args> reference emplace_back( Args&&...args);		(since C++17) (constexpr since C++20)

Appends a new element to the end of the container. The element is constructed throughstd::allocator_traits::construct, which typically uses placementnew to construct the element in-place at the location provided by the container. The argumentsargs... are forwarded to the constructor asstd::forward<Args>(args)....

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 theend() iterator is invalidated.

[edit]Parameters

args	-	arguments to forward to the constructor of the element
Type requirements
- If any of the following conditions is satisfied, the behavior is undefined: `T` is notEmplaceConstructible into`vector` fromargs.... `T` is notMoveInsertable into`vector`.

[edit]Return value

(none)	(until C++17)
A reference to the inserted element.	(since C++17)

[edit]Complexity

Amortized constant.

[edit]Exceptions

If an exception is thrown for any reason, this function has no effect (strong exception safety guarantee).If the move constructor ofT is notnoexcept and is notCopyInsertable into*this,vector will use the throwing move constructor. If it throws, the guarantee is waived and the effects are unspecified.

Notes

Since reallocation may take place,emplace_back requires the element type to beMoveInsertable forvector.

[edit]Example

The following code usesemplace_back to append an object of typePresident to astd::vector. It demonstrates howemplace_back forwards parameters to thePresident constructor and shows how usingemplace_back avoids the extra copy or move operation required when usingpush_back.

Run this code

#include <vector>#include <cassert>#include <iostream>#include <string> struct President{std::string name;std::string country;int year;     President(std::string p_name,std::string p_country,int p_year): name(std::move(p_name)), country(std::move(p_country)), year(p_year){std::cout<<"I am being constructed.\n";}     President(President&& other): name(std::move(other.name)), country(std::move(other.country)), year(other.year){std::cout<<"I am being moved.\n";}     President& operator=(const President& other)=default;}; int main(){std::vector<President> elections;std::cout<<"emplace_back:\n";auto& ref= elections.emplace_back("Nelson Mandela","South Africa",1994);assert(ref.year==1994&&"uses a reference to the created object (C++17)"); std::vector<President> reElections;std::cout<<"\npush_back:\n";    reElections.push_back(President("Franklin Delano Roosevelt","the USA",1936)); std::cout<<"\nContents:\n";for(const President& president: elections)std::cout<< president.name<<" was elected president of "<< president.country<<" in "<< president.year<<".\n"; for(const President& president: reElections)std::cout<< president.name<<" was re-elected president of "<< president.country<<" in "<< president.year<<".\n";}

Output:

emplace_back:I am being constructed. push_back:I am being constructed.I am being moved. Contents:Nelson Mandela was elected president of South Africa in 1994.Franklin Delano Roosevelt was re-elected president of the USA in 1936.