std::vector

The vector class is similar to a std::array, but is re-sizable. There are two separate properties of a std::vector: the size() is the number of items stored in the array in indices 0 through size() - 1. The capacity is the memory allocated to store entries, and the capacity must always be greater than or equal to the size.

Declaring a std::vector (constructor)

The following are a subset of the possible declarations of a vector.

std::vector<typename&gr; identifier{ item_0, item_1, ... }

This declares the identifier to be an instance of the std::vector class that holds objects of the type typename. It is initialized with the entries item_0, item_1, ..., and the size and capacity equal the number of entries in this initialization list (and this initialization list may be empty, in which case, the size and capacity are zero).

std::vector<typename&gr; identifier( std::size_t n )
std::vector<typename&gr; identifier( std::size_t n, typename item )

Both of these declare a std::vector where the size and the capacity are n. The entries are initialized to the default value of typename and item, respectively.

std::vector<typename&gr; identifier( itr_t itr_first, itr_t itr_last )

Given iterators that refer to entries in another container that also store objects of typename, this creates a vector with size and capacity equal to the number of items in the given range and then initializes the entries with the items being referred to in the given order.

Accessing entries

The member indexing operator and the at(...) member function can both be used to access the entries in the vector:

T operator[]( std::size_t k )

Access the $k$ entry, and if $k$ is outside the range from 0 to size() - 1, this operator will allow such an access. This is intended to be fast, as there is no argument checking.

T at( std::size_t k )

This is like the previous function, but if the argument is outside the range 0 to size() - 1, an exception is thrown.

T front()

This accesses the entry at index 0, and if the array is empty, the behavior is undefined.

T back()

This accesses the entry at index size() - 1, and if the array is empty, the behavior is undefined.

Size and capacity of a std::vector

The following member functions return information about the size and capacity:

bool empty()

Returns true if size() == 0, and false otherwise.

std::size_t size()

Returns the current number of items in the std::vector.

std::size_t capacity()

Returns the maximum number of items that could be stored in the vector without needing a reallocation of memory.

Iterators

The two most common iterator-returning functions are presented here:

itr_t begin() const
itr_t end() const

These return a range from the first to the last entries in the std::vector object. The following two are equivalent:

     std::vector<<i>T> v{...};
     // Manipulate entries of 'v', change the size, etc.

     for ( std::size_t k{ 0 }; k != v.size(); ++k ) {
       std::cout << v[k] << std::endl;
     }

     // Iterators only step through the size,
     //   and not the capacity.
     for ( auto itr{ 0 }; itr != v.end(); ++itr ) {
       std::cout << *itr << std::endl;
     }

Changing size or capacity of a std::vector

void push_back( T const & item )

This increases the size of the std::vector by one and inserts the new item at what used to be index size(). If the new size is greater than the current capacity, a reallocation of memory must occur, but the new capacity may be larger than the increased size. The assumption is that if you are performing push_back(...) once, you are likely to do so again.

void pop_back()

Removes the last entry by reducing the size by one, and thus, the popped entry is no longer accessible, at least by the at(...) member function or back().

itr_t insert( itr_t itr_posn, Tconst & item )
itr_t insert( itr_t itr_posn, std::size_t count, Tconst & item )
itr_t insert( itr_t itr_posn, itr_t itr_first, itr_t itr_last )
itr_t insert( itr_t itr_posn, {item_0, ...} )

All of these insert zero or more items at the location indicated by the iterator itr_posn, and all return an iterator just beyond the last inserted item, so that itr_posn and the returned iterator form a range spanning the newly inserted items. The iterator itr_posn must not equal that returned by end().

In all cases, the size is increased by the number of inserted items, and if this is greater than the current capacity, a reallocation of memory must occur. The new capacity may be larger than the increased size. The assumption is that if you are performing insert(...) once, you are likely to do so again.

The first inserts the item at the indicated location.

The second inserts count copies of item at the indicated location.

The third inserts all items in the range indicated by the iterators itr_first and itr_last into the vector at the location indicated by itr_posn.

The last inserts all the items between the braces at the position indicated.

itr_t erase( itr_t itr_posn )
itr_t erase( itr_t itr_first, itr_t itr_last )

All of these remove the items referred to by the iterators from the vector and return an iterator to the location immediately after the last item removed (possibly including returning end()).

The first removes the item at the location indicated by itr_posn and reduces the size by one. The iterator must not be equal to end().

The second removes all items on the indicated range and reduces the size by that number.

void std::reserve( std::size_t new_capacity )

If new_capacity is greater than the current capacity, then there will occur a reallocation of memory so that the new capacity is at least equal to new_capacity. This member function will never decrease the capacity, and thus, never decrease the size.

void std::clear()

The clear() member function sets the size to 0, but does not change the capacity.

void std::shrink_to_fit()

The shrink_to_fit() member function does nothing if the size equals the current capacity, but if the current capacity is greater than the size, a reallocation of memory occurs, and the new capacity will equal the current size.

Non-member functions

To additional functions are provided for by the #Include <vector> library:

size_t erase( std::vector<T> v, T item )
size_t erase_if( std::vector<T> v, bool predicate( T ) )

The first removes all items in the vector that equal item.

The second removes all items in the vector for which calling the Boolean-valued predicate function returns true.

Both return the number of items removed, and both reduce the size by that number.

You can see the use of the std::vector class at replit.com.