<vector>

template<
  class T,
  class Allocator = std::allocator<T>
> class vector;

// since C++17
namespace pmr {
  template< class T >
  using vector = std::vector<T, std::pmr::polymorphic_allocator<T>>;
}

std::vector is a sequence container that encapsulates dynamic size arrays.

std::pmr::vector is a alias template that uses a polymorphoc allocator.

Except for the std::vector<bool> partial specialization, the elements are stored contiguosly, which means that elements can be accessed not only through iterators, but also using offsets to regular pointers to elements. This means that a pointer to an element of a vector may be passed to any function that exects a pointer to an element of an array.

The storage of the vector is handled automatically, being expanded as needed. Vectors usually occupy more space that static arrays, because more memory is allocated to handle future growth. This way a vector does not need to reallocate each time an elements is inserted, but only when the additional memory is exhausted. The total amount of allocated memory can be queried using capacity() function. Extra memory can be returned to the system via a call to shrink_to_fit().

Reallocations are usually costly operations in terms of performance. The reserve() function can be used to eliminate reallocations if the number of elements is known beforehand.

The complexity (effciency) of common operations on vectors is as follows:

• Random access - conatant

• Insertion or removal of elements at the end - amortized constant.

• Insertion or removal of elements - linear in the distance to the end of the vector.

Allmember functions of std::vector are constexpr: it is possible to create a use std::vector objects in the evaluation of a constant expression. However, std::vector objects generally cannot be constexpr, because any dynamically allocated storage must be released in the same evaluation of constant expression.

Specializations

The standard library provides a specialization of std::vector for the type bool, which may be optimized for space efficiency.

vector	space-efficient dynamic bitset

Iterator invalidation

operations	invalidated
All read only operations	Never.
swap, std::swap	end
clear, operator=, assign	Always.
reserve, shrink_to_fit	If the vector changed capacity, all of them. If not, none.
erase	Erased elements and all elements after them (including end())
push_back, emplace_back	If the vector changed capacity, all of them.
insert, emplace	If the vector changed capacity, all of them. If not, only end() and any elements erased.
pop_back	The elements erased and end().

Member types

member type	Definition
value_type	T
allocator_type	Allocator
size_type	unsigned integer type (usually std::size_t)
difference_type	Signed integer type (usually std::ptrdiff_t)
reference	value_type&
const_reference	const value_type&
pointer	Allocator::pointer (until c++11); std::allocator_traits::pointer (since c++11)
const_pointer	Allocator::const_pointer (until c++11); std::allocator_traits::const_pointer (since c++11)
iterator
const_iterator
reverse_iterator	std::reverse_iterator
const_reverse_iterator	std::reverse_iterator<const_iterator>

Member functions

Name	Definition
(constructor)	constructs the vector
(destructor)	destructs the vector
operator=	assigns values to the container
assign	assigns values to the container
assign_range (C++23)	assigns a range of values to the container
get_allocator	returns the associated allocator
Element access	Definition
--------------	--------------------------------------------------
at	access specified element with bounds checking
operator[]	access specified element
front	access the first element
back	access the last element
data	direct access to the underlying contiguous storage
Iterators	Definition
---------------------	-------------------------------------------
begin/cbegin(c++11)	returns an iterator to the beginning
end/cend(c++11)	returns an iterator to the end
rbegin/crbegin(c++11)	returns a reverse iterator to the beginning
rend/crend(c++11)	returns a reverse iterator to the end
Capacity	Definition
-------------	------------------------------------------------------------------------------
empty	checks whether the container is empty
size	returns the number of elements
max_size	returns the maximum possible number of elements
reserve	reserves storage
capacity	returns the number of elements that can be held in currently allocated storage
shrink_to_fit	reduces memory usage by freeing unused memory
Modifiers	Definition
-------------------	-----------------------------------------
clear	clear the contents
insert	inserts elements
insert_range(c++23)	inserts a range of elements
emplace(c++11)	constructs elements in-place
erase	erases elements
push_back	adds an element to the end
emplace_back(c++11)	constructs an element in-place at the end
append_range(c++23)	adds a range of elements to the end
pop_back	removes the last element
resize	changes the number of elements stored
swap	swaps the contents

Non-member functions

Name	Definition
operator==
operator!=	removed in c++20
operator<	removed in c++20
operator<=	removed in c++20
operator>	removed in c++20
operator>=	removed in c++20
operator<=>	c++20
std::swap(std::vector)	specializes the std::swap algorithm
erase(std::vector)/ease_if(std::vector) (c++20)	erases all elements satisfying specific criteria

Example

#include <iostream>
#include <vector>

int main() {
  // Create a vector containing integers
  std::vector<int> v = {8, 4, 5, 9};

  // Add two more integers to vector
  v.push_back(6);
  v.push_back(9);

  // Overwrite element at position 2
  v[2] = -1

  // Print out the vector
  for (int n : v) {
    std::cout << n << " ";
  }
  std::cout << "\n";
}

// Output
// 8 4 -1 9 6 9