Przejdź do głównej zawartości

std::vector emplace_back() method

// prism-push-types:reference
// Non const version only
template< class... Args >
constexpr reference emplace_back( Args&&... args );

Appends a new element to the end of the container. The element is constructed through std::allocator_traits<Alloc>::construct(), which typically uses placement-new to construct the element in-place at the location provided by the container. The arguments args... are forwarded to the constructor as std::forward<Args>(args)....

Invalidation

If the new size() is greater than capacity() then all iterators and references (including the past-the-end iterator) are invalidated.

Otherwise only the past-the-end iterator is invalidated.

Parameters

  • args - arguments to forward to the constructor of the element

Type requirements

Return value

A reference to the inserted element.

Complexity

Amortized constant - O(1).

Exceptions

If an exception is thrown, this function has no effect (strong exception guarantee).

If T's move constructor is not noexcept and T is not CopyInsertable 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 be MoveInsertable for vectors.

Example

Main.cpp
#include <vector>
#include <string>
#include <cassert>
#include <iostream>

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 (President const& president: elections) {
std::cout << president.name << " was elected president of "
<< president.country << " in " << president.year << ".\n";
}
for (President const& 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.
This article originates from this CppReference page. It was likely altered for improvements or editors' preference. Click "Edit this page" to see all changes made to this document.
Hover to see the original license.

std::vector emplace_back() method

// prism-push-types:reference
// Non const version only
template< class... Args >
constexpr reference emplace_back( Args&&... args );

Appends a new element to the end of the container. The element is constructed through std::allocator_traits<Alloc>::construct(), which typically uses placement-new to construct the element in-place at the location provided by the container. The arguments args... are forwarded to the constructor as std::forward<Args>(args)....

Invalidation

If the new size() is greater than capacity() then all iterators and references (including the past-the-end iterator) are invalidated.

Otherwise only the past-the-end iterator is invalidated.

Parameters

  • args - arguments to forward to the constructor of the element

Type requirements

Return value

A reference to the inserted element.

Complexity

Amortized constant - O(1).

Exceptions

If an exception is thrown, this function has no effect (strong exception guarantee).

If T's move constructor is not noexcept and T is not CopyInsertable 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 be MoveInsertable for vectors.

Example

Main.cpp
#include <vector>
#include <string>
#include <cassert>
#include <iostream>

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 (President const& president: elections) {
std::cout << president.name << " was elected president of "
<< president.country << " in " << president.year << ".\n";
}
for (President const& 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.
This article originates from this CppReference page. It was likely altered for improvements or editors' preference. Click "Edit this page" to see all changes made to this document.
Hover to see the original license.