Class template vector

boost::container::vector

Synopsis

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

template<typename T, typename A = std::allocator<T> > 
class vector {
public:
  // types
  typedef T                                       value_type;            
  typedef allocator_traits_type::pointer          pointer;                 // Pointer to T. 
  typedef allocator_traits_type::const_pointer    const_pointer;           // Const pointer to T. 
  typedef allocator_traits_type::reference        reference;               // Reference to T. 
  typedef allocator_traits_type::const_reference  const_reference;         // Const reference to T. 
  typedef allocator_traits_type::size_type        size_type;               // An unsigned integral type. 
  typedef allocator_traits_type::difference_type  difference_type;         // A signed integral type. 
  typedef A                                       allocator_type;          // The allocator type. 
  typedef unspecified                             iterator;                // The random access iterator. 
  typedef unspecified                             const_iterator;          // The random access const_iterator. 
  typedef std::reverse_iterator< iterator >       reverse_iterator;        // Iterator used to iterate backwards through a vector. 
  typedef std::reverse_iterator< const_iterator > const_reverse_iterator;  // Const iterator used to iterate backwards through a vector. 
  typedef allocator_type                          stored_allocator_type;   // The stored allocator type. 

  // construct/copy/destruct
  vector();
  explicit vector(const A &);
  explicit vector(size_type);
  vector(size_type, const T &, const allocator_type & = allocator_type());
  vector(const vector &);
  vector(vector &&);
  template<typename InIt> 
    vector(InIt, InIt, const allocator_type & = allocator_type());
  vector& operator=(const vector &);
  vector& operator=(vector &&);
  ~vector();

  // public member functions
  iterator begin();
  const_iterator begin() const;
  iterator end();
  const_iterator end() const;
  reverse_iterator rbegin();
  const_reverse_iterator rbegin() const;
  reverse_iterator rend();
  const_reverse_iterator rend() const;
  const_iterator cbegin() const;
  const_iterator cend() const;
  const_reverse_iterator crbegin() const;
  const_reverse_iterator crend() const;
  reference front();
  const_reference front() const;
  reference back();
  const_reference back() const;
  pointer data();
  const_pointer data() const;
  size_type size() const;
  size_type max_size() const;
  size_type capacity() const;
  bool empty() const;
  reference operator[](size_type);
  const_reference operator[](size_type) const;
  reference at(size_type);
  const_reference at(size_type) const;
  allocator_type get_allocator() const;
  const stored_allocator_type & get_stored_allocator() const;
  stored_allocator_type & get_stored_allocator();
  void reserve(size_type);
  void assign(size_type, const value_type &);
  template<typename InIt> void assign(InIt, InIt);
  void push_back(const T &);
  void push_back(T &&);
  template<class... Args> void emplace_back(Args &&...);
  template<class... Args> iterator emplace(const_iterator, Args &&...);
  void swap(vector &);
  iterator insert(const_iterator, const T &);
  iterator insert(const_iterator, T &&);
  template<typename InIt> void insert(const_iterator, InIt, InIt);
  void insert(const_iterator, size_type, const T &);
  void pop_back();
  iterator erase(const_iterator);
  iterator erase(const_iterator, const_iterator);
  void resize(size_type, const T &);
  void resize(size_type);
  void clear();
  void shrink_to_fit();
};

Description

A 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 vector may vary dynamically; memory management is automatic. boost::container::vector is similar to std::vector but it's compatible with shared memory and memory mapped files.

`vector` public types

typedef T value_type;

The type of object, T, stored in the vector

`vector` public construct/copy/destruct

```
vector();
```
Effects: Constructs a vector taking the allocator as parameter.

Throws: If allocator_type's default constructor throws.

Complexity: Constant.
```
explicit vector(const A & a);
```
Effects: Constructs a vector taking the allocator as parameter.

Throws: Nothing

Complexity: Constant.
```
explicit vector(size_type n);
```
Effects: Constructs a vector that will use a copy of allocator a and inserts n default contructed values.

Throws: If allocator_type's default constructor or allocation throws or T's default constructor throws.

Complexity: Linear to n.
```
vector(size_type n, const T & value, 
       const allocator_type & a = allocator_type());
```
Effects: Constructs a vector that will use a copy of allocator a and inserts n copies of value.

Throws: If allocator_type's default constructor or allocation throws or T's copy constructor throws.

Complexity: Linear to n.
```
vector(const vector & x);
```
Effects: Copy constructs a vector.

Postcondition: x == *this.

Throws: If allocator_type's default constructor or allocation throws or T's copy constructor throws.

Complexity: Linear to the elements x contains.
```
vector(vector && mx);
```
Effects: Move constructor. Moves mx's resources to *this.

Throws: Nothing

Complexity: Constant.
```
template<typename InIt> 
  vector(InIt first, InIt last, const allocator_type & a = allocator_type());
```
Effects: Constructs a vector that will use a copy of allocator a and inserts a copy of the range [first, last) in the vector.

Throws: If allocator_type's default constructor or allocation throws or T's constructor taking an dereferenced InIt throws.

Complexity: Linear to the range [first, last).
```
vector& operator=(const vector & x);
```
Effects: Makes *this contain the same elements as x.

Postcondition: this->size() == x.size(). *this contains a copy of each of x's elements.

Throws: If memory allocation throws or T's copy/move constructor/assignment throws.

Complexity: Linear to the number of elements in x.
```
vector& operator=(vector && x);
```
Effects: Move assignment. All mx's values are transferred to *this.

Postcondition: x.empty(). *this contains a the elements x had before the function.

Throws: Nothing

Complexity: Linear.
```
~vector();
```
Effects: Destroys the vector. All stored values are destroyed and used memory is deallocated.

Throws: Nothing.

Complexity: Linear to the number of elements.

`vector` public member functions

```
iterator begin();
```
Effects: Returns an iterator to the first element contained in the vector.

Throws: Nothing.

Complexity: Constant.
```
const_iterator begin() const;
```
Effects: Returns a const_iterator to the first element contained in the vector.

Throws: Nothing.

Complexity: Constant.
```
iterator end();
```
Effects: Returns an iterator to the end of the vector.

Throws: Nothing.

Complexity: Constant.
```
const_iterator end() const;
```
Effects: Returns a const_iterator to the end of the vector.

Throws: Nothing.

Complexity: Constant.
```
reverse_iterator rbegin();
```
Effects: Returns a reverse_iterator pointing to the beginning of the reversed vector.

Throws: Nothing.

Complexity: Constant.
```
const_reverse_iterator rbegin() const;
```
Effects: Returns a const_reverse_iterator pointing to the beginning of the reversed vector.

Throws: Nothing.

Complexity: Constant.
```
reverse_iterator rend();
```
Effects: Returns a reverse_iterator pointing to the end of the reversed vector.

Throws: Nothing.

Complexity: Constant.
```
const_reverse_iterator rend() const;
```
Effects: Returns a const_reverse_iterator pointing to the end of the reversed vector.

Throws: Nothing.

Complexity: Constant.
```
const_iterator cbegin() const;
```
Effects: Returns a const_iterator to the first element contained in the vector.

Throws: Nothing.

Complexity: Constant.
```
const_iterator cend() const;
```
Effects: Returns a const_iterator to the end of the vector.

Throws: Nothing.

Complexity: Constant.
```
const_reverse_iterator crbegin() const;
```
Effects: Returns a const_reverse_iterator pointing to the beginning of the reversed vector.

Throws: Nothing.

Complexity: Constant.
```
const_reverse_iterator crend() const;
```
Effects: Returns a const_reverse_iterator pointing to the end of the reversed vector.

Throws: Nothing.

Complexity: Constant.
```
reference front();
```
Requires: !empty()

Effects: Returns a reference to the first element of the container.

Throws: Nothing.

Complexity: Constant.
```
const_reference front() const;
```
Requires: !empty()

Effects: Returns a const reference to the first element of the container.

Throws: Nothing.

Complexity: Constant.
```
reference back();
```
Requires: !empty()

Effects: Returns a reference to the last element of the container.

Throws: Nothing.

Complexity: Constant.
```
const_reference back() const;
```
Requires: !empty()

Effects: Returns a const reference to the last element of the container.

Throws: Nothing.

Complexity: Constant.
```
pointer data();
```
Returns: A pointer such that [data(),data() + size()) is a valid range. For a non-empty vector, data() == &front().

Throws: Nothing.

Complexity: Constant.
```
const_pointer data() const;
```
Returns: A pointer such that [data(),data() + size()) is a valid range. For a non-empty vector, data() == &front().

Throws: Nothing.

Complexity: Constant.
```
size_type size() const;
```
Effects: Returns the number of the elements contained in the vector.

Throws: Nothing.

Complexity: Constant.
```
size_type max_size() const;
```
Effects: Returns the largest possible size of the vector.

Throws: Nothing.

Complexity: Constant.
```
size_type capacity() const;
```
Effects: Number of elements for which memory has been allocated. capacity() is always greater than or equal to size().

Throws: Nothing.

Complexity: Constant.
```
bool empty() const;
```
Effects: Returns true if the vector contains no elements.

Throws: Nothing.

Complexity: Constant.
```
reference operator[](size_type n);
```
Requires: size() > n.

Effects: Returns a reference to the nth element from the beginning of the container.

Throws: Nothing.

Complexity: Constant.
```
const_reference operator[](size_type n) const;
```
Requires: size() > n.

Effects: Returns a const reference to the nth element from the beginning of the container.

Throws: Nothing.

Complexity: Constant.
```
reference at(size_type n);
```
Requires: size() > n.

Effects: Returns a reference to the nth element from the beginning of the container.

Throws: std::range_error if n >= size()

Complexity: Constant.
```
const_reference at(size_type n) const;
```
Requires: size() > n.

Effects: Returns a const reference to the nth element from the beginning of the container.

Throws: std::range_error if n >= size()

Complexity: Constant.
```
allocator_type get_allocator() const;
```
Effects: Returns a copy of the internal allocator.

Throws: If allocator's copy constructor throws.

Complexity: Constant.
```
const stored_allocator_type & get_stored_allocator() const;
```
Effects: Returns a reference to the internal allocator.

Throws: Nothing

Complexity: Constant.

Note: Non-standard extension.
```
stored_allocator_type & get_stored_allocator();
```
Effects: Returns a reference to the internal allocator.

Throws: Nothing

Complexity: Constant.

Note: Non-standard extension.
```
void reserve(size_type new_cap);
```
Effects: If n is less than or equal to capacity(), this call has no effect. Otherwise, it is a request for allocation of additional memory. If the request is successful, then capacity() is greater than or equal to n; otherwise, capacity() is unchanged. In either case, size() is unchanged.

Throws: If memory allocation allocation throws or T's copy/move constructor throws.
```
void assign(size_type n, const value_type & val);
```
Effects: Assigns the n copies of val to *this.

Throws: If memory allocation throws or T's copy/move constructor/assignment throws.

Complexity: Linear to n.
```
template<typename InIt> void assign(InIt first, InIt last);
```
Effects: Assigns the the range [first, last) to *this.

Throws: If memory allocation throws or T's copy/move constructor/assignment or T's constructor/assignment from dereferencing InpIt throws.

Complexity: Linear to n.
```
void push_back(const T & x);
```
Effects: Inserts a copy of x at the end of the vector.

Throws: If memory allocation throws or T's copy/move constructor throws.

Complexity: Amortized constant time.
```
void push_back(T && x);
```
Effects: Constructs a new element in the end of the vector and moves the resources of mx to this new element.

Throws: If memory allocation throws or T's move constructor throws.

Complexity: Amortized constant time.
```
template<class... Args> void emplace_back(Args &&... args);
```
Effects: Inserts an object of type T constructed with std::forward<Args>(args)... in the end of the vector.

Throws: If memory allocation throws or the in-place constructor throws or T's move constructor throws.

Complexity: Amortized constant time.
```
template<class... Args> 
  iterator emplace(const_iterator position, Args &&... args);
```
Requires: position must be a valid iterator of *this.

Effects: Inserts an object of type T constructed with std::forward<Args>(args)... before position

Throws: If memory allocation throws or the in-place constructor throws or T's move constructor/assignment throws.

Complexity: If position is end(), amortized constant time Linear time otherwise.
```
void swap(vector & x);
```
Effects: Swaps the contents of *this and x.

Throws: Nothing.

Complexity: Constant.
```
iterator insert(const_iterator position, const T & x);
```
Requires: position must be a valid iterator of *this.

Effects: Insert a copy of x before position.

Throws: If memory allocation throws or T's copy/move constructor/assignment throws.

Complexity: If position is end(), amortized constant time Linear time otherwise.
```
iterator insert(const_iterator position, T && x);
```
Requires: position must be a valid iterator of *this.

Effects: Insert a new element before position with mx's resources.

Throws: If memory allocation throws.

Complexity: If position is end(), amortized constant time Linear time otherwise.
```
template<typename InIt> void insert(const_iterator pos, InIt first, InIt last);
```
Requires: pos must be a valid iterator of *this.

Effects: Insert a copy of the [first, last) range before pos.

Throws: If memory allocation throws, T's constructor from a dereferenced InpIt throws or T's copy/move constructor/assignment throws.

Complexity: Linear to std::distance [first, last).
```
void insert(const_iterator p, size_type n, const T & x);
```
Requires: pos must be a valid iterator of *this.

Effects: Insert n copies of x before pos.

Throws: If memory allocation throws or T's copy constructor throws.

Complexity: Linear to n.
```
void pop_back();
```
Effects: Removes the last element from the vector.

Throws: Nothing.

Complexity: Constant time.
```
iterator erase(const_iterator position);
```
Effects: Erases the element at position pos.

Throws: Nothing.

Complexity: Linear to the elements between pos and the last element. Constant if pos is the last element.
```
iterator erase(const_iterator first, const_iterator last);
```
Effects: Erases the elements pointed by [first, last).

Throws: Nothing.

Complexity: Linear to the distance between first and last plus linear to the elements between pos and the last element.
```
void resize(size_type new_size, const T & x);
```
Effects: Inserts or erases elements at the end such that the size becomes n. New elements are copy constructed from x.

Throws: If memory allocation throws, or T's copy constructor throws.

Complexity: Linear to the difference between size() and new_size.
```
void resize(size_type new_size);
```
Effects: Inserts or erases elements at the end such that the size becomes n. New elements are default constructed.

Throws: If memory allocation throws, or T's copy constructor throws.

Complexity: Linear to the difference between size() and new_size.
```
void clear();
```
Effects: Erases all the elements of the vector.

Throws: Nothing.

Complexity: Linear to the number of elements in the vector.
```
void shrink_to_fit();
```
Effects: Tries to deallocate the excess of memory created with previous allocations. The size of the vector is unchanged

Throws: If memory allocation throws, or T's copy/move constructor throws.

Complexity: Linear to size().

Class template vector

Synopsis

Description

vector public types

vector public construct/copy/destruct

vector public member functions

`vector` public types

`vector` public construct/copy/destruct

`vector` public member functions