| Home | Libraries | People | FAQ | More

## Class template vector

boost::container::vector

## Synopsis

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

    template<typename T, typename Allocator = std::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();
      explicit vector(const Allocator &);
      explicit vector(size_type);
      vector(size_type, const T &, const allocator_type & = allocator_type());
      template<typename InIt>
        vector(InIt, InIt, const allocator_type & = allocator_type());
      vector(const vector &);
      vector(vector &&);
      vector(const vector &, const allocator_type &);
      vector(vector &&, const allocator_type &);
      vector& operator=(const vector &);
      vector& operator=(vector &&);
      ~vector();

      // public member functions
      template<typename InIt> void assign(InIt, InIt);
      void assign(size_type, const value_type &);
      allocator_type get_allocator() const;
      stored_allocator_type & get_stored_allocator();
      const stored_allocator_type & get_stored_allocator() const;
      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;
      bool empty() const;
      size_type size() const;
      size_type max_size() const;
      void resize(size_type);
      void resize(size_type, const T &);
      size_type capacity() const;
      void reserve(size_type);
      void shrink_to_fit();
      reference front();
      const_reference front() const;
      reference back();
      const_reference back() const;
      reference operator[](size_type);
      const_reference operator[](size_type) const;
      reference at(size_type);
      const_reference at(size_type) const;
      T * data();
      const T * data() const;
      template<class... Args> void 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);
      void pop_back();
      iterator erase(const_iterator);
      iterator erase(const_iterator, const_iterator);
      void swap(vector &);
      void clear();
    };

## 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 construct/copy/destruct

1.     vector();

   Effects: Constructs a vector taking the allocator as parameter.

   Throws: If allocator_type's default constructor throws.

   Complexity: Constant.

2.     explicit vector(const Allocator & a);

   Effects: Constructs a vector taking the allocator as parameter.

   Throws: Nothing

   Complexity: Constant.

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

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

5.     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).

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

7.     vector(vector && mx);

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

   Throws: Nothing

   Complexity: Constant.

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

   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.

9.     vector(vector && mx, const allocator_type & a);

   Effects: Move constructor using the specified allocator. Moves mx'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 == mx.get_allocator(), linear otherwise.

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

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

12.     ~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);

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

3.     allocator_type get_allocator() const;

   Effects: Returns a copy of the internal allocator.

   Throws: If allocator's copy constructor throws.

   Complexity: Constant.

4.     stored_allocator_type & get_stored_allocator();

   Effects: Returns a reference to the internal allocator.

   Throws: Nothing

   Complexity: Constant.

   Note: Non-standard extension.

5.     const stored_allocator_type & get_stored_allocator() const;

   Effects: Returns a reference to the internal allocator.

   Throws: Nothing

   Complexity: Constant.

   Note: Non-standard extension.

6.     iterator begin();

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

   Throws: Nothing.

   Complexity: Constant.

7.     const_iterator begin() const;

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

   Throws: Nothing.

   Complexity: Constant.

8.     iterator end();

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

   Throws: Nothing.

   Complexity: Constant.

9.     const_iterator end() const;

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

   Throws: Nothing.

   Complexity: Constant.

10.     reverse_iterator rbegin();

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

    Throws: Nothing.

    Complexity: Constant.

11.     const_reverse_iterator rbegin() const;

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

    Throws: Nothing.

    Complexity: Constant.

12.     reverse_iterator rend();

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

    Throws: Nothing.

    Complexity: Constant.

13.     const_reverse_iterator rend() const;

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

    Throws: Nothing.

    Complexity: Constant.

14.     const_iterator cbegin() const;

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

    Throws: Nothing.

    Complexity: Constant.

15.     const_iterator cend() const;

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

    Throws: Nothing.

    Complexity: Constant.

16.     const_reverse_iterator crbegin() const;

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

    Throws: Nothing.

    Complexity: Constant.

17.     const_reverse_iterator crend() const;

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

    Throws: Nothing.

    Complexity: Constant.

18.     bool empty() const;

    Effects: Returns true if the vector contains no elements.

    Throws: Nothing.

    Complexity: Constant.

19.     size_type size() const;

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

    Throws: Nothing.

    Complexity: Constant.

20.     size_type max_size() const;

    Effects: Returns the largest possible size of the vector.

    Throws: Nothing.

    Complexity: Constant.

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

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

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

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

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

26.     reference front();

    Requires: !empty()

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

    Throws: Nothing.

    Complexity: Constant.

27.     const_reference front() const;

    Requires: !empty()

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

    Throws: Nothing.

    Complexity: Constant.

28.     reference back();

    Requires: !empty()

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

    Throws: Nothing.

    Complexity: Constant.

29.     const_reference back() const;

    Requires: !empty()

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

    Throws: Nothing.

    Complexity: Constant.

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

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

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

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

34.     T * data();

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

    Throws: Nothing.

    Complexity: Constant.

35.     const T * data() const;

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

    Throws: Nothing.

    Complexity: Constant.

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

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

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

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

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

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

42.     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 constructor throws.

    Complexity: Linear to n.

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

    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 std::distance [first, last).

44.     void pop_back();

    Effects: Removes the last element from the vector.

    Throws: Nothing.

    Complexity: Constant time.

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

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

47.     void swap(vector & x);

    Effects: Swaps the contents of *this and x.

    Throws: Nothing.

    Complexity: Constant.

48.     void clear();

    Effects: Erases all the elements of the vector.

    Throws: Nothing.

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