CKTIS / C++
std::vector::push_back — appending one element
Append one element by copying or from an rvalue. Learn when growth invalidates pointers and why the old `end()` is invalid even when no reallocation occurs.
Version: ISO C++23; implementation support may vary
Syntax
#include <vector>
// Member declarations inside std::vector<T, Allocator> (C++23):
constexpr void push_back(const T& value);
constexpr void push_back(T&& value);
// Call on a non-const vector object v:
v.push_back(value);std::vector::push_back is a member function of the vector declared in <vector>. It appends one element and returns void. The const T& overload copies the argument and requires T to be Cpp17CopyInsertable into that vector. The T&& overload requires Cpp17MoveInsertable and constructs the element from an rvalue; this can still copy if there is no move constructor and a copy constructor accepts the argument. std::move does not itself move anything. Do not assume a moved-from std::string is empty.
On success, size() increases by one. capacity() is how many elements the vector can hold without reallocating. A successful reserve(n) ensures capacity of at least n but creates no elements and does not change size(). Appending takes amortized O(1) time; a single append that reallocates takes time linear in the vector's size.
If the new size exceeds the old capacity, reallocation invalidates all existing element pointers, references, and iterators. Without reallocation, those remain valid, but the old end() iterator is invalidated by every successful append. Reserving capacity alone therefore does not make it safe to append to the same vector while traversing it with a range-based for loop.
An allocation failure leaves the vector unchanged. The strong exception guarantee also applies if T is Cpp17CopyInsertable or std::is_nothrow_move_constructible_v<T> is true. If the move constructor of a type that is not Cpp17CopyInsertable throws, however, the effects are unspecified.
Use emplace_back(args...) to construct an element directly from constructor arguments. If an algorithm needs an output iterator, writing through std::back_inserter(v) from <iterator> calls v.push_back(...). The iterator v.end() is not a destination for writing new elements.
Examples
#include <iostream>
#include <string>
#include <utility>
#include <vector>
int main() {
std::vector<std::string> words;
words.reserve(2);
std::cout << words.size() << '\n';
const std::string alpha{"alpha"};
words.push_back(alpha);
const std::string* first = &words.front();
std::string beta{"beta"};
words.push_back(std::move(beta));
std::cout << words.size() << ' ' << *first << ' ' << words.back() << '\n';
}Result
0 2 alpha beta
`reserve(2)` leaves the size at `0`. The first call copies `alpha`, and the second moves from `beta`. No reallocation occurs, so `first` still points to the first element. The program does not read `beta` after the move.
Related lessons
- C++ · Lesson 11 · Advanced · Version: 3
- C++ · Lesson 14 · Advanced · Version: 3
- C++ · Lesson 15 · Advanced · Version: 3
- C++ · Lesson 21 · Advanced · Version: 3
- C++ · Lesson 23 · Advanced · Version: 3
- C++ · Lesson 29 · Advanced · Version: 3
- C++ · Lesson 30 · Advanced · Version: 3
- C++ · Lesson 34 · Advanced · Version: 3
- C++ · Lesson 37 · Advanced · Version: 3
- C++ · Lesson 51 · Advanced · Version: 3
- C++ · Lesson 57 · Advanced · Version: 3
- C++ · Lesson 58 · Advanced · Version: 3
- C++ · Lesson 59 · Advanced · Version: 3
Sources
- C++ working draft — [vector.modifiers]
- C++ working draft — [vector.capacity]
- C++ working draft — [vector.overview]
- C++ working draft — [sequence.reqmts]
- C++ working draft — [container.alloc.reqmts]
- C++ working draft — [lib.types.movedfrom]
- C++ working draft — [back.insert.iterator]
- WG21 N4950 — Working Draft, Standard for Programming Language C++