Class template static_vector

boost::container::static_vector — A variable-size array container with fixed capacity.

Synopsis

// In header: <boost/container/static_vector.hpp>

template<typename Value, std::size_t Capacity> 
class static_vector {
public:
  // types
  typedef base_t::value_type             value_type;              // The type of elements stored in the container. 
  typedef base_t::size_type              size_type;               // The unsigned integral type used by the container. 
  typedef base_t::difference_type        difference_type;         // The pointers difference type. 
  typedef base_t::pointer                pointer;                 // The pointer type. 
  typedef base_t::const_pointer          const_pointer;           // The const pointer type. 
  typedef base_t::reference              reference;               // The value reference type. 
  typedef base_t::const_reference        const_reference;         // The value const reference type. 
  typedef base_t::iterator               iterator;                // The iterator type. 
  typedef base_t::const_iterator         const_iterator;          // The const iterator type. 
  typedef base_t::reverse_iterator       reverse_iterator;        // The reverse iterator type. 
  typedef base_t::const_reverse_iterator const_reverse_iterator;  // The const reverse iterator. 

  // construct/copy/destruct
  static_vector();
  explicit static_vector(size_type);
  static_vector(size_type, value_type const &);
  template<typename Iterator> static_vector(Iterator, Iterator);
  static_vector(static_vector const &);
  template<std::size_t C> 
    static_vector(static_vector< value_type, C > const &);
  static_vector(static_vector &&);
  template<std::size_t C> static_vector(static_vector< value_type, C > &&);
  static_vector& operator=(const static_vector &);
  template<std::size_t C> 
    static_vector& operator=(static_vector< value_type, C > const &);
  static_vector& operator=(static_vector &&);
  template<std::size_t C> 
    static_vector& operator=(static_vector< value_type, C > &&);
  ~static_vector();

  // public member functions
  void swap(static_vector &);
  template<std::size_t C> void swap(static_vector< value_type, C > &);
  void resize(size_type);
  void resize(size_type, value_type const &);
  void reserve(size_type);
  void push_back(value_type const &);
  void push_back(value_type &&);
  void pop_back();
  iterator insert(iterator, value_type const &);
  iterator insert(iterator, value_type &&);
  iterator insert(iterator, size_type, value_type const &);
  template<typename Iterator> iterator insert(iterator, Iterator, Iterator);
  iterator erase(iterator);
  iterator erase(iterator, iterator);
  template<typename Iterator> void assign(Iterator, Iterator);
  void assign(size_type, value_type const &);
  template<class... Args> void emplace_back(Args &&...);
  template<class... Args> iterator emplace(iterator, Args &&...);
  void clear();
  reference at(size_type);
  const_reference at(size_type) const;
  reference operator[](size_type);
  const_reference operator[](size_type) const;
  reference front();
  const_reference front() const;
  reference back();
  const_reference back() const;
  Value * data();
  const Value * data() const;
  iterator begin();
  const_iterator begin() const;
  const_iterator cbegin() const;
  iterator end();
  const_iterator end() const;
  const_iterator cend() const;
  reverse_iterator rbegin();
  const_reverse_iterator rbegin() const;
  const_reverse_iterator crbegin() const;
  reverse_iterator rend();
  const_reverse_iterator rend() const;
  const_reverse_iterator crend() const;
  size_type size() const;
  bool empty() const;

  // public static functions
  static size_type capacity();
  static size_type max_size();
};

Description

static_vector is a sequence container like boost::container::vector with contiguous storage that can change in size, along with the static allocation, low overhead, and fixed capacity of boost::array.

A static_vector is a sequence that supports random access to elements, constant time insertion and removal of elements at the end, and linear time insertion and removal of elements at the beginning or in the middle. The number of elements in a static_vector may vary dynamically up to a fixed capacity because elements are stored within the object itself similarly to an array. However, objects are initialized as they are inserted into static_vector unlike C arrays or std::array which must construct all elements on instantiation. The behavior of static_vector enables the use of statically allocated elements in cases with complex object lifetime requirements that would otherwise not be trivially possible.

Error Handling. Insertion beyond the capacity and out of bounds errors results in calling throw_bad_alloc(). The reason for this is because unlike vectors, static_vector does not perform allocation.

Template Parameters

```
typename Value
```
The type of element that will be stored.
```
std::size_t Capacity
```
The maximum number of elements static_vector can store, fixed at compile time.

`static_vector` public construct/copy/destruct

```
static_vector();
```
Constructs an empty static_vector.
Throws. Nothing.

Complexity. Constant O(1).
```
explicit static_vector(size_type count);
```
Constructs a static_vector containing count default constructed Values.

Throws. If Value's default constructor throws.

Complexity. Linear O(N).

Parameters:

count

The number of values which will be contained in the container.

Requires:

count <= capacity()

static_vector(size_type count, value_type const & value);

Constructs a static_vector containing count copies of value.

Throws. If Value's copy constructor throws.

Complexity. Linear O(N).

Parameters:

`count`	The number of copies of a values that will be contained in the container.
`value`	The value which will be used to copy construct values.

Requires:

count <= capacity()

template<typename Iterator> static_vector(Iterator first, Iterator last);

Constructs a static_vector containing copy of a range [first, last).

Throws. If Value's constructor taking a dereferenced Iterator throws.

Complexity. Linear O(N).

Parameters:

`first`	The iterator to the first element in range.
`last`	The iterator to the one after the last element in range.

Requires:

distance(first, last) <= capacity()
Iterator must meet the ForwardTraversalIterator concept.

```
static_vector(static_vector const & other);
```
Constructs a copy of other static_vector.

Throws. If Value's copy constructor throws.

Complexity. Linear O(N).

Parameters:

other

The static_vector which content will be copied to this one.
```
template<std::size_t C> 
  static_vector(static_vector< value_type, C > const & other);
```
Constructs a copy of other static_vector.

Throws. If Value's copy constructor throws.

Complexity. Linear O(N).

Parameters:

other

The static_vector which content will be copied to this one.

Requires:

other.size() <= capacity().
```
static_vector(static_vector && other);
```
Move constructor. Moves Values stored in the other static_vector to this one.

Throws.
- If boost::has_nothrow_move<Value>::value is true and Value's move constructor throws.
- If boost::has_nothrow_move<Value>::value is false and Value's copy constructor throws.
Complexity. Linear O(N).

Parameters:

other

The static_vector which content will be moved to this one.
```
template<std::size_t C> static_vector(static_vector< value_type, C > && other);
```
Move constructor. Moves Values stored in the other static_vector to this one.

Throws.
- If boost::has_nothrow_move<Value>::value is true and Value's move constructor throws.
- If boost::has_nothrow_move<Value>::value is false and Value's copy constructor throws.
Complexity. Linear O(N).

Parameters:

other

The static_vector which content will be moved to this one.

Requires:

other.size() <= capacity()
```
static_vector& operator=(const static_vector & other);
```
Copy assigns Values stored in the other static_vector to this one.

Throws. If Value's copy constructor or copy assignment throws.

Complexity. Linear O(N).

Parameters:

other

The static_vector which content will be copied to this one.
```
template<std::size_t C> 
  static_vector& operator=(static_vector< value_type, C > const & other);
```
Copy assigns Values stored in the other static_vector to this one.

Throws. If Value's copy constructor or copy assignment throws.

Complexity. Linear O(N).

Parameters:

other

The static_vector which content will be copied to this one.

Requires:

other.size() <= capacity()
```
static_vector& operator=(static_vector && other);
```
Move assignment. Moves Values stored in the other static_vector to this one.

Throws.
- If boost::has_nothrow_move<Value>::value is true and Value's move constructor or move assignment throws.
- If boost::has_nothrow_move<Value>::value is false and Value's copy constructor or copy assignment throws.
Complexity. Linear O(N).

Parameters:

other

The static_vector which content will be moved to this one.
```
template<std::size_t C> 
  static_vector& operator=(static_vector< value_type, C > && other);
```
Move assignment. Moves Values stored in the other static_vector to this one.

Throws.
- If boost::has_nothrow_move<Value>::value is true and Value's move constructor or move assignment throws.
- If boost::has_nothrow_move<Value>::value is false and Value's copy constructor or copy assignment throws.
Complexity. Linear O(N).

Parameters:

other

The static_vector which content will be moved to this one.

Requires:

other.size() <= capacity()
```
~static_vector();
```
Destructor. Destroys Values stored in this container.
Throws. Nothing

Complexity. Linear O(N).

`static_vector` public member functions

```
void swap(static_vector & other);
```
Swaps contents of the other static_vector and this one.

Throws.
- If boost::has_nothrow_move<Value>::value is true and Value's move constructor or move assignment throws,
- If boost::has_nothrow_move<Value>::value is false and Value's copy constructor or copy assignment throws,
Complexity. Linear O(N).

Parameters:

other

The static_vector which content will be swapped with this one's content.
```
template<std::size_t C> void swap(static_vector< value_type, C > & other);
```
Swaps contents of the other static_vector and this one.

Throws.
- If boost::has_nothrow_move<Value>::value is true and Value's move constructor or move assignment throws,
- If boost::has_nothrow_move<Value>::value is false and Value's copy constructor or copy assignment throws,
Complexity. Linear O(N).

Parameters:

other

The static_vector which content will be swapped with this one's content.

Requires:

other.size() <= capacity() && size() <= other.capacity()
```
void resize(size_type count);
```
Inserts or erases elements at the end such that the size becomes count. New elements are default constructed.

Throws. If Value's default constructor throws.

Complexity. Linear O(N).

Parameters:

count

The number of elements which will be stored in the container.

Requires:

count <= capacity()
```
void resize(size_type count, value_type const & value);
```
Inserts or erases elements at the end such that the size becomes count. New elements are copy constructed from value.

Throws. If Value's copy constructor throws.

Complexity. Linear O(N).

Parameters:

count

The number of elements which will be stored in the container.

value

The value used to copy construct the new element.

Requires:

count <= capacity()
```
void reserve(size_type count);
```
This call has no effect because the Capacity of this container is constant.

Throws. Nothing.

Complexity. Linear O(N).

Parameters:

count

The number of elements which the container should be able to contain.

Requires:

count <= capacity()
```
void push_back(value_type const & value);
```
Adds a copy of value at the end.

Throws. If Value's copy constructor throws.

Complexity. Constant O(1).

Parameters:

value

The value used to copy construct the new element.

Requires:

size() < capacity()
```
void push_back(value_type && value);
```
Moves value to the end.

Throws. If Value's move constructor throws.

Complexity. Constant O(1).

Parameters:

value

The value to move construct the new element.

Requires:

size() < capacity()
```
void pop_back();
```
Destroys last value and decreases the size.

Throws. Nothing by default.

Complexity. Constant O(1).

Requires:

!empty()

iterator insert(iterator position, value_type const & value);

Inserts a copy of element at position.

Throws.

If Value's copy constructor or copy assignment throws
If Value's move constructor or move assignment throws.

Complexity. Constant or linear.

Parameters:

`position`	The position at which the new value will be inserted.
`value`	The value used to copy construct the new element.

Requires:

position must be a valid iterator of *this in range [begin(), end()].
size() < capacity()

iterator insert(iterator position, value_type && value);

Inserts a move-constructed element at position.

Throws. If Value's move constructor or move assignment throws.

Complexity. Constant or linear.

Parameters:

`position`	The position at which the new value will be inserted.
`value`	The value used to move construct the new element.

Requires:

position must be a valid iterator of *this in range [begin(), end()].
size() < capacity()

iterator insert(iterator position, size_type count, value_type const & value);

Inserts a count copies of value at position.

Throws.

If Value's copy constructor or copy assignment throws.
If Value's move constructor or move assignment throws.

Complexity. Linear O(N).

Parameters:

`count`	The number of new elements which will be inserted.
`position`	The position at which new elements will be inserted.
`value`	The value used to copy construct new elements.

Requires:

position must be a valid iterator of *this in range [begin(), end()].
size() + count <= capacity()

template<typename Iterator> 
  iterator insert(iterator position, Iterator first, Iterator last);

Inserts a copy of a range [first, last) at position.

Throws.

If Value's constructor and assignment taking a dereferenced Iterator.
If Value's move constructor or move assignment throws.

Complexity. Linear O(N).

Parameters:

`first`	The iterator to the first element of a range used to construct new elements.
`last`	The iterator to the one after the last element of a range used to construct new elements.
`position`	The position at which new elements will be inserted.

Requires:

position must be a valid iterator of *this in range [begin(), end()].
distance(first, last) <= capacity()
Iterator must meet the ForwardTraversalIterator concept.

```
iterator erase(iterator position);
```
Erases Value from position.

Throws. If Value's move assignment throws.

Complexity. Linear O(N).

Parameters:

position

The position of the element which will be erased from the container.

Requires:

position must be a valid iterator of *this in range [begin(), end())

iterator erase(iterator first, iterator last);

Erases Values from a range [first, last).

Throws. If Value's move assignment throws.

Complexity. Linear O(N).

Parameters:

`first`	The position of the first element of a range which will be erased from the container.
`last`	The position of the one after the last element of a range which will be erased from the container.

Requires:

first and last must define a valid range
iterators must be in range [begin(), end()]

template<typename Iterator> void assign(Iterator first, Iterator last);

Assigns a range [first, last) of Values to this container.

Throws. If Value's copy constructor or copy assignment throws,

Complexity. Linear O(N).

Parameters:

`first`	The iterator to the first element of a range used to construct new content of this container.
`last`	The iterator to the one after the last element of a range used to construct new content of this container.

Requires:

distance(first, last) <= capacity()

void assign(size_type count, value_type const & value);

Assigns a count copies of value to this container.

Throws. If Value's copy constructor or copy assignment throws.

Complexity. Linear O(N).

Parameters:

`count`	The new number of elements which will be container in the container.
`value`	The value which will be used to copy construct the new content.

Requires:

count <= capacity()

```
template<class... Args> void emplace_back(Args &&... args);
```
Inserts a Value constructed with std::forward<Args>(args)... in the end of the container.

Throws. If in-place constructor throws or Value's move constructor throws.

Complexity. Constant O(1).

Parameters:

args

The arguments of the constructor of the new element which will be created at the end of the container.

Requires:

size() < capacity()

template<class... Args> iterator emplace(iterator position, Args &&... args);

Inserts a Value constructed with std::forward<Args>(args)... before position.

Throws. If in-place constructor throws or if Value's move constructor or move assignment throws.

Complexity. Constant or linear.

Parameters:

`args`	The arguments of the constructor of the new element.
`position`	The position at which new elements will be inserted.

Requires:

position must be a valid iterator of *this in range [begin(), end()]
size() < capacity()

```
void clear();
```
Removes all elements from the container.
Throws. Nothing.

Complexity. Constant O(1).
```
reference at(size_type i);
```
Returns reference to the i-th element.

Throws. std::out_of_range exception by default.

Complexity. Constant O(1).

Parameters:

i

The element's index.

Requires:

i < size()

Returns:

reference to the i-th element from the beginning of the container.
```
const_reference at(size_type i) const;
```
Returns const reference to the i-th element.

Throws. std::out_of_range exception by default.

Complexity. Constant O(1).

Parameters:

i

The element's index.

Requires:

i < size()

Returns:

const reference to the i-th element from the beginning of the container.
```
reference operator[](size_type i);
```
Returns reference to the i-th element.

Throws. Nothing by default.

Complexity. Constant O(1).

Parameters:

i

The element's index.

Requires:

i < size()

Returns:

reference to the i-th element from the beginning of the container.
```
const_reference operator[](size_type i) const;
```
Returns const reference to the i-th element.

Throws. Nothing by default.

Complexity. Constant O(1).

Parameters:

i

The element's index.

Requires:

i < size()

Returns:

const reference to the i-th element from the beginning of the container.
```
reference front();
```
Returns reference to the first element.

Throws. Nothing by default.

Complexity. Constant O(1).

Requires:

!empty()

Returns:

reference to the first element from the beginning of the container.
```
const_reference front() const;
```
Returns const reference to the first element.

Throws. Nothing by default.

Complexity. Constant O(1).

Requires:

!empty()

Returns:

const reference to the first element from the beginning of the container.
```
reference back();
```
Returns reference to the last element.

Throws. Nothing by default.

Complexity. Constant O(1).

Requires:

!empty()

Returns:

reference to the last element from the beginning of the container.
```
const_reference back() const;
```
Returns const reference to the first element.

Throws. Nothing by default.

Complexity. Constant O(1).

Requires:

!empty()

Returns:

const reference to the last element from the beginning of the container.
```
Value * data();
```
Pointer such that [data(), data() + size()) is a valid range. For a non-empty vector data() == &front().
Throws. Nothing.

Complexity. Constant O(1).
```
const Value * data() const;
```
Const pointer such that [data(), data() + size()) is a valid range. For a non-empty vector data() == &front().
Throws. Nothing.

Complexity. Constant O(1).
```
iterator begin();
```
Returns iterator to the first element.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

iterator to the first element contained in the vector.
```
const_iterator begin() const;
```
Returns const iterator to the first element.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

const_iterator to the first element contained in the vector.
```
const_iterator cbegin() const;
```
Returns const iterator to the first element.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

const_iterator to the first element contained in the vector.
```
iterator end();
```
Returns iterator to the one after the last element.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

iterator pointing to the one after the last element contained in the vector.
```
const_iterator end() const;
```
Returns const iterator to the one after the last element.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

const_iterator pointing to the one after the last element contained in the vector.
```
const_iterator cend() const;
```
Returns const iterator to the one after the last element.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

const_iterator pointing to the one after the last element contained in the vector.
```
reverse_iterator rbegin();
```
Returns reverse iterator to the first element of the reversed container.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

reverse_iterator pointing to the beginning of the reversed static_vector.
```
const_reverse_iterator rbegin() const;
```
Returns const reverse iterator to the first element of the reversed container.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

const_reverse_iterator pointing to the beginning of the reversed static_vector.
```
const_reverse_iterator crbegin() const;
```
Returns const reverse iterator to the first element of the reversed container.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

const_reverse_iterator pointing to the beginning of the reversed static_vector.
```
reverse_iterator rend();
```
Returns reverse iterator to the one after the last element of the reversed container.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

reverse_iterator pointing to the one after the last element of the reversed static_vector.
```
const_reverse_iterator rend() const;
```
Returns const reverse iterator to the one after the last element of the reversed container.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

const_reverse_iterator pointing to the one after the last element of the reversed static_vector.
```
const_reverse_iterator crend() const;
```
Returns const reverse iterator to the one after the last element of the reversed container.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

const_reverse_iterator pointing to the one after the last element of the reversed static_vector.
```
size_type size() const;
```
Returns the number of stored elements.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

Number of elements contained in the container.
```
bool empty() const;
```
Queries if the container contains elements.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

true if the number of elements contained in the container is equal to 0.

`static_vector` public static functions

```
static size_type capacity();
```
Returns container's capacity.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

container's capacity.
```
static size_type max_size();
```
Returns container's capacity.

Throws. Nothing.

Complexity. Constant O(1).

Returns:

container's capacity.

Requires:	`!empty`()
Returns:	reference to the first element from the beginning of the container.

Boost C++ Libraries