Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

Class template vector

boost::container::vector

Synopsis

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

template<typename T, typename Allocator = new_allocator<T> > 
class vector {
public:
  // types
  typedef T                                                                  value_type;            
  typedef ::boost::container::allocator_traits< Allocator >::pointer         pointer;               
  typedef ::boost::container::allocator_traits< Allocator >::const_pointer   const_pointer;         
  typedef ::boost::container::allocator_traits< Allocator >::reference       reference;             
  typedef ::boost::container::allocator_traits< Allocator >::const_reference const_reference;       
  typedef ::boost::container::allocator_traits< Allocator >::size_type       size_type;             
  typedef ::boost::container::allocator_traits< Allocator >::difference_type difference_type;       
  typedef Allocator                                                          allocator_type;        
  typedef Allocator                                                          stored_allocator_type; 
  typedef implementation_defined                                             iterator;              
  typedef implementation_defined                                             const_iterator;        
  typedef implementation_defined                                             reverse_iterator;      
  typedef implementation_defined                                             const_reverse_iterator;

  // construct/copy/destruct
  vector() noexcept;
  explicit vector(const allocator_type &) noexcept;
  explicit vector(size_type);
  vector(size_type, default_init_t);
  explicit vector(size_type, const allocator_type &);
  vector(size_type, default_init_t, const allocator_type &);
  vector(size_type, const T &);
  vector(size_type, const T &, const allocator_type &);
  template<typename InIt> vector(InIt, InIt);
  template<typename InIt> vector(InIt, InIt, const allocator_type &);
  vector(const vector &);
  vector(vector &&) noexcept;
  vector(std::initializer_list< value_type >, 
         const allocator_type & = allocator_type());
  vector(const vector &, const allocator_type &);
  vector(vector &&, const allocator_type &);
  vector & operator=(const vector &);
  vector & operator=(std::initializer_list< value_type >);
  vector & operator=(vector &&) noexcept(allocator_traits_type::propagate_on_container_move_assignment::value||allocator_traits_type::is_always_equal::value));
  ~vector();

  // public member functions
  template<typename InIt> void assign(InIt, InIt last );
  void assign(std::initializer_list< T >);
  template<typename FwdIt> void assign(FwdIt, FwdIt last );
  void assign(size_type, const value_type &);
  allocator_type get_allocator() const noexcept;
  stored_allocator_type & get_stored_allocator() noexcept;
  const stored_allocator_type & get_stored_allocator() const noexcept;
  iterator begin() noexcept;
  const_iterator begin() const noexcept;
  iterator end() noexcept;
  const_iterator end() const noexcept;
  reverse_iterator rbegin() noexcept;
  const_reverse_iterator rbegin() const noexcept;
  reverse_iterator rend() noexcept;
  const_reverse_iterator rend() const noexcept;
  const_iterator cbegin() const noexcept;
  const_iterator cend() const noexcept;
  const_reverse_iterator crbegin() const noexcept;
  const_reverse_iterator crend() const noexcept;
  bool empty() const noexcept;
  size_type size() const noexcept;
  size_type max_size() const noexcept;
  void resize(size_type);
  void resize(size_type, default_init_t);
  void resize(size_type, const T &);
  size_type capacity() const noexcept;
  void reserve(size_type);
  void shrink_to_fit();
  reference front() noexcept;
  const_reference front() const noexcept;
  reference back() noexcept;
  const_reference back() const noexcept;
  reference operator[](size_type) noexcept;
  const_reference operator[](size_type) const noexcept;
  iterator nth(size_type) noexcept;
  const_iterator nth(size_type) const noexcept;
  size_type index_of(iterator) noexcept;
  size_type index_of(const_iterator) const noexcept;
  reference at(size_type);
  const_reference at(size_type) const;
  T * data() noexcept;
  const T * data() const noexcept;
  template<class... Args> void emplace_back(Args &&...);
  template<class... Args> bool stable_emplace_back(Args &&...);
  template<class... Args> iterator emplace(const_iterator, Args &&...);
  void push_back(const T &);
  void push_back(T &&);
  iterator insert(const_iterator, const T &);
  iterator insert(const_iterator, T &&);
  iterator insert(const_iterator, size_type, const T &);
  template<typename InIt> iterator insert(const_iterator, InIt, InIt last );
  iterator insert(const_iterator, std::initializer_list< value_type >);
  void pop_back() noexcept;
  iterator erase(const_iterator);
  iterator erase(const_iterator, const_iterator);
  void swap(vector &) noexcept(((allocator_traits_type::propagate_on_container_swap::value||allocator_traits_type::is_always_equal::value)&&!container_detail::is_version< Allocator, 0 >::value)));
  void clear() noexcept;

  // friend functions
  friend bool operator==(const vector &, const vector &);
  friend bool operator!=(const vector &, const vector &);
  friend bool operator<(const vector &, const vector &);
  friend bool operator>(const vector &, const vector &);
  friend bool operator<=(const vector &, const vector &);
  friend bool operator>=(const vector &, const vector &);
  friend void swap(vector &, vector &);
};

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.

Template Parameters

  1. typename T

    The type of object that is stored in the vector

  2. typename Allocator = new_allocator<T>

    The allocator used for all internal memory management

vector public construct/copy/destruct

  1. vector() noexcept;

    Effects: Constructs a vector taking the allocator as parameter.

    Throws: Nothing.

    Complexity: Constant.

  2. explicit vector(const allocator_type & a) noexcept;

    Effects: Constructs a vector taking the allocator as parameter.

    Throws: Nothing

    Complexity: Constant.

  3. explicit vector(size_type n);

    Effects: Constructs a vector and inserts n value initialized values.

    Throws: If allocator_type's allocation throws or T's value initialization throws.

    Complexity: Linear to n.

  4. vector(size_type n, default_init_t);

    Effects: Constructs a vector that will use a copy of allocator a and inserts n default initialized values.

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

    Complexity: Linear to n.

    Note: Non-standard extension

  5. explicit vector(size_type n, const allocator_type & a);

    Effects: Constructs a vector that will use a copy of allocator a and inserts n value initialized values.

    Throws: If allocator_type's allocation throws or T's value initialization throws.

    Complexity: Linear to n.

  6. vector(size_type n, default_init_t, const allocator_type & a);

    Effects: Constructs a vector that will use a copy of allocator a and inserts n default initialized values.

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

    Complexity: Linear to n.

    Note: Non-standard extension

  7. vector(size_type n, const T & value);

    Effects: Constructs a vector and inserts n copies of value.

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

    Complexity: Linear to n.

  8. vector(size_type n, const T & value, const allocator_type & a);

    Effects: Constructs a vector that will use a copy of allocator a and inserts n copies of value.

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

    Complexity: Linear to n.

  9. template<typename InIt> vector(InIt first, InIt last);

    Effects: Constructs a vector and inserts a copy of the range [first, last) in the vector.

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

    Complexity: Linear to the range [first, last).

  10. template<typename InIt> 
      vector(InIt first, InIt last, const allocator_type & a);

    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 allocation throws or T's constructor taking a dereferenced InIt throws.

    Complexity: Linear to the range [first, last).

  11. vector(const vector & x);

    Effects: Copy constructs a vector.

    Postcondition: x == *this.

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

    Complexity: Linear to the elements x contains.

  12. vector(vector && x) noexcept;

    Effects: Move constructor. Moves x's resources to *this.

    Throws: Nothing

    Complexity: Constant.

  13. vector(std::initializer_list< value_type > il, 
           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 [il.begin(), il.last()) in the vector

    Throws: If T's constructor taking a dereferenced initializer_list iterator throws.

    Complexity: Linear to the range [il.begin(), il.end()).

  14. vector(const vector & x, const allocator_type & a);
    defined(BOOST_CONTAINER_DOXYGEN_INVOKED)

    Effects: Copy constructs a vector using the specified allocator.

    Postcondition: x == *this.

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

    Complexity: Linear to the elements x contains.

  15. vector(vector && x, const allocator_type & a);

    Effects: Move constructor using the specified allocator. Moves x's resources to *this if a == allocator_type(). Otherwise copies values from x to *this.

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

    Complexity: Constant if a == x.get_allocator(), linear otherwise.

  16. 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.

  17. vector & operator=(std::initializer_list< value_type > il);

    Effects: Make *this container contains elements from il.

    Complexity: Linear to the range [il.begin(), il.end()).

  18. vector & operator=(vector && x) noexcept(allocator_traits_type::propagate_on_container_move_assignment::value||allocator_traits_type::is_always_equal::value));

    Effects: Move assignment. All x's values are transferred to *this.

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

    Throws: If allocator_traits_type::propagate_on_container_move_assignment is false and (allocation throws or value_type's move constructor throws)

    Complexity: Constant if allocator_traits_type:: propagate_on_container_move_assignment is true or this->get>allocator() == x.get_allocator(). Linear otherwise.

  19. ~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

  1. template<typename InIt> 
      void assign(InIt first, InIt last  BOOST_CONTAINER_DOCIGN);

    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.

  2. void assign(std::initializer_list< T > il);

    Effects: Assigns the the range [il.begin(), il.end()) to *this.

    Throws: If memory allocation throws or T's constructor from dereferencing iniializer_list iterator throws.

  3. template<typename FwdIt> 
      void assign(FwdIt first, FwdIt last  BOOST_CONTAINER_DOCIGN);

    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.

  4. 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.

  5. allocator_type get_allocator() const noexcept;

    Effects: Returns a copy of the internal allocator.

    Throws: If allocator's copy constructor throws.

    Complexity: Constant.

  6. stored_allocator_type & get_stored_allocator() noexcept;

    Effects: Returns a reference to the internal allocator.

    Throws: Nothing

    Complexity: Constant.

    Note: Non-standard extension.

  7. const stored_allocator_type & get_stored_allocator() const noexcept;

    Effects: Returns a reference to the internal allocator.

    Throws: Nothing

    Complexity: Constant.

    Note: Non-standard extension.

  8. iterator begin() noexcept;

    Effects: Returns an iterator to the first element contained in the vector.

    Throws: Nothing.

    Complexity: Constant.

  9. const_iterator begin() const noexcept;

    Effects: Returns a const_iterator to the first element contained in the vector.

    Throws: Nothing.

    Complexity: Constant.

  10. iterator end() noexcept;

    Effects: Returns an iterator to the end of the vector.

    Throws: Nothing.

    Complexity: Constant.

  11. const_iterator end() const noexcept;

    Effects: Returns a const_iterator to the end of the vector.

    Throws: Nothing.

    Complexity: Constant.

  12. reverse_iterator rbegin() noexcept;

    Effects: Returns a reverse_iterator pointing to the beginning of the reversed vector.

    Throws: Nothing.

    Complexity: Constant.

  13. const_reverse_iterator rbegin() const noexcept;

    Effects: Returns a const_reverse_iterator pointing to the beginning of the reversed vector.

    Throws: Nothing.

    Complexity: Constant.

  14. reverse_iterator rend() noexcept;

    Effects: Returns a reverse_iterator pointing to the end of the reversed vector.

    Throws: Nothing.

    Complexity: Constant.

  15. const_reverse_iterator rend() const noexcept;

    Effects: Returns a const_reverse_iterator pointing to the end of the reversed vector.

    Throws: Nothing.

    Complexity: Constant.

  16. const_iterator cbegin() const noexcept;

    Effects: Returns a const_iterator to the first element contained in the vector.

    Throws: Nothing.

    Complexity: Constant.

  17. const_iterator cend() const noexcept;

    Effects: Returns a const_iterator to the end of the vector.

    Throws: Nothing.

    Complexity: Constant.

  18. const_reverse_iterator crbegin() const noexcept;

    Effects: Returns a const_reverse_iterator pointing to the beginning of the reversed vector.

    Throws: Nothing.

    Complexity: Constant.

  19. const_reverse_iterator crend() const noexcept;

    Effects: Returns a const_reverse_iterator pointing to the end of the reversed vector.

    Throws: Nothing.

    Complexity: Constant.

  20. bool empty() const noexcept;

    Effects: Returns true if the vector contains no elements.

    Throws: Nothing.

    Complexity: Constant.

  21. size_type size() const noexcept;

    Effects: Returns the number of the elements contained in the vector.

    Throws: Nothing.

    Complexity: Constant.

  22. size_type max_size() const noexcept;

    Effects: Returns the largest possible size of the vector.

    Throws: Nothing.

    Complexity: Constant.

  23. void resize(size_type new_size);

    Effects: Inserts or erases elements at the end such that the size becomes n. New elements are value initialized.

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

    Complexity: Linear to the difference between size() and new_size.

  24. void resize(size_type new_size, default_init_t);

    Effects: Inserts or erases elements at the end such that the size becomes n. New elements are default initialized.

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

    Complexity: Linear to the difference between size() and new_size.

    Note: Non-standard extension

  25. 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/move constructor throws.

    Complexity: Linear to the difference between size() and new_size.

  26. size_type capacity() const noexcept;

    Effects: Number of elements for which memory has been allocated. capacity() is always greater than or equal to size().

    Throws: Nothing.

    Complexity: Constant.

  27. 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.

  28. 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().

  29. reference front() noexcept;

    Requires: !empty()

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

    Throws: Nothing.

    Complexity: Constant.

  30. const_reference front() const noexcept;

    Requires: !empty()

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

    Throws: Nothing.

    Complexity: Constant.

  31. reference back() noexcept;

    Requires: !empty()

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

    Throws: Nothing.

    Complexity: Constant.

  32. const_reference back() const noexcept;

    Requires: !empty()

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

    Throws: Nothing.

    Complexity: Constant.

  33. reference operator[](size_type n) noexcept;

    Requires: size() > n.

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

    Throws: Nothing.

    Complexity: Constant.

  34. const_reference operator[](size_type n) const noexcept;

    Requires: size() > n.

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

    Throws: Nothing.

    Complexity: Constant.

  35. iterator nth(size_type n) noexcept;

    Requires: size() >= n.

    Effects: Returns an iterator to the nth element from the beginning of the container. Returns end() if n == size().

    Throws: Nothing.

    Complexity: Constant.

    Note: Non-standard extension

  36. const_iterator nth(size_type n) const noexcept;

    Requires: size() >= n.

    Effects: Returns a const_iterator to the nth element from the beginning of the container. Returns end() if n == size().

    Throws: Nothing.

    Complexity: Constant.

    Note: Non-standard extension

  37. size_type index_of(iterator p) noexcept;

    Requires: size() >= n.

    Effects: Returns an iterator to the nth element from the beginning of the container. Returns end() if n == size().

    Throws: Nothing.

    Complexity: Constant.

    Note: Non-standard extension

  38. size_type index_of(const_iterator p) const noexcept;

    Requires: begin() <= p <= end().

    Effects: Returns the index of the element pointed by p and size() if p == end().

    Throws: Nothing.

    Complexity: Constant.

    Note: Non-standard extension

  39. 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.

  40. 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.

  41. T * data() noexcept;

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

    Throws: Nothing.

    Complexity: Constant.

  42. const T * data() const noexcept;

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

    Throws: Nothing.

    Complexity: Constant.

  43. 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 copy/move constructor throws.

    Complexity: Amortized constant time.

  44. template<class... Args> bool stable_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 the in-place constructor throws.

    Complexity: Constant time.

    Note: Non-standard extension.

  45. 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 copy/move constructor/assignment throws.

    Complexity: If position is end(), amortized constant time Linear time otherwise.

  46. 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.

  47. void push_back(T && x);

    Effects: Constructs a new element in the end of the vector and moves the resources of x to this new element.

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

    Complexity: Amortized constant time.

  48. 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.

  49. iterator insert(const_iterator position, T && x);

    Requires: position must be a valid iterator of *this.

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

    Throws: If memory allocation throws.

    Complexity: If position is end(), amortized constant time Linear time otherwise.

  50. iterator insert(const_iterator p, size_type n, const T & x);

    Requires: p must be a valid iterator of *this.

    Effects: Insert n copies of x before pos.

    Returns: an iterator to the first inserted element or p if n is 0.

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

    Complexity: Linear to n.

  51. template<typename InIt> 
      iterator insert(const_iterator pos, InIt first, 
                      InIt last  BOOST_CONTAINER_DOCIGN);

    Requires: p must be a valid iterator of *this.

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

    Returns: an iterator to the first inserted element or pos if first == last.

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

    Complexity: Linear to boost::container::iterator_distance [first, last).

  52. iterator insert(const_iterator position, 
                    std::initializer_list< value_type > il);

    Requires: p must be a valid iterator of *this. num, must be equal to boost::container::iterator_distance(first, last)

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

    Returns: an iterator to the first inserted element or pos if first == last.

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

    Complexity: Linear to boost::container::iterator_distance [first, last).

    Note: This function avoids a linear operation to calculate boost::container::iterator_distance[first, last) for forward and bidirectional iterators, and a one by one insertion for input iterators. This is a a non-standard extension. Requires: position must be a valid iterator of *this.

    Effects: Insert a copy of the [il.begin(), il.end()) range before position.

    Returns: an iterator to the first inserted element or position if first == last.

    Complexity: Linear to the range [il.begin(), il.end()).

  53. void pop_back() noexcept;

    Effects: Removes the last element from the vector.

    Throws: Nothing.

    Complexity: Constant time.

  54. 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.

  55. 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.

  56. void swap(vector & x) noexcept(((allocator_traits_type::propagate_on_container_swap::value||allocator_traits_type::is_always_equal::value)&&!container_detail::is_version< Allocator, 0 >::value)));

    Effects: Swaps the contents of *this and x.

    Throws: Nothing.

    Complexity: Constant.

  57. void clear() noexcept;

    Effects: Erases all the elements of the vector.

    Throws: Nothing.

    Complexity: Linear to the number of elements in the container.

vector friend functions

  1. friend bool operator==(const vector & x, const vector & y);

    Effects: Returns true if x and y are equal

    Complexity: Linear to the number of elements in the container.

  2. friend bool operator!=(const vector & x, const vector & y);

    Effects: Returns true if x and y are unequal

    Complexity: Linear to the number of elements in the container.

  3. friend bool operator<(const vector & x, const vector & y);

    Effects: Returns true if x is less than y

    Complexity: Linear to the number of elements in the container.

  4. friend bool operator>(const vector & x, const vector & y);

    Effects: Returns true if x is greater than y

    Complexity: Linear to the number of elements in the container.

  5. friend bool operator<=(const vector & x, const vector & y);

    Effects: Returns true if x is equal or less than y

    Complexity: Linear to the number of elements in the container.

  6. friend bool operator>=(const vector & x, const vector & y);

    Effects: Returns true if x is equal or greater than y

    Complexity: Linear to the number of elements in the container.

  7. friend void swap(vector & x, vector & y);

    Effects: x.swap(y)

    Complexity: Constant.


PrevUpHomeNext