| Home | Libraries | People | FAQ | More

## Class template deque

boost::container::deque

## Synopsis

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

    template<typename T, typename A = std::allocator<T> >
    class deque {
    public:
      // types
      typedef Base::iterator                          iterator;
      typedef Base::const_iterator                    const_iterator;
      typedef std::reverse_iterator< const_iterator > const_reverse_iterator;
      typedef std::reverse_iterator< iterator >       reverse_iterator;

      // construct/copy/destruct
      explicit deque(const allocator_type & = allocator_type());
      explicit deque(size_type);
      deque(size_type, const value_type &,
            const allocator_type & = allocator_type());
      deque(const deque &);
      deque(deque &&);
      template<typename InpIt>
        deque(InpIt, InpIt, const allocator_type & = allocator_type());
      deque& operator=(const deque &);
      deque& operator=(deque &&);
      ~deque();

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

## Description

Deque class

### `deque` public construct/copy/destruct

1.     explicit deque(const allocator_type & a = allocator_type());

   Effects: Constructs a deque taking the allocator as parameter.

   Throws: If allocator_type's copy constructor throws.

   Complexity: Constant.

2.     explicit deque(size_type n);

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

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

   Complexity: Linear to n.

3.     deque(size_type n, const value_type & value,
             const allocator_type & a = allocator_type());

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

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

   Complexity: Linear to n.

4.     deque(const deque & x);

   Effects: Copy constructs a deque.

   Postcondition: x == *this.

   Complexity: Linear to the elements x contains.

5.     deque(deque && mx);

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

   Throws: If allocator_type's copy constructor throws.

   Complexity: Constant.

6.     template<typename InpIt>
         deque(InpIt first, InpIt last, const allocator_type & a = allocator_type());

   Effects: Constructs a deque that will use a copy of allocator a and inserts a copy of the range [first, last) in the deque.

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

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

7.     deque& operator=(const deque & 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 constructor throws.

   Complexity: Linear to the number of elements in x.

8.     deque& operator=(deque && 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: If allocator_type's copy constructor throws.

   Complexity: Linear.

9.     ~deque();

   Effects: Destroys the deque. All stored values are destroyed and used memory is deallocated.

   Throws: Nothing.

   Complexity: Linear to the number of elements.

### `deque` public member functions

1.     allocator_type get_allocator() const;

   Effects: Returns a copy of the internal allocator.

   Throws: If allocator's copy constructor throws.

   Complexity: Constant.

2.     iterator begin();

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

   Throws: Nothing.

   Complexity: Constant.

3.     iterator end();

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

   Throws: Nothing.

   Complexity: Constant.

4.     const_iterator begin() const;

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

   Throws: Nothing.

   Complexity: Constant.

5.     const_iterator end() const;

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

   Throws: Nothing.

   Complexity: Constant.

6.     reverse_iterator rbegin();

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

   Throws: Nothing.

   Complexity: Constant.

7.     reverse_iterator rend();

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

   Throws: Nothing.

   Complexity: Constant.

8.     const_reverse_iterator rbegin() const;

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

   Throws: Nothing.

   Complexity: Constant.

9.     const_reverse_iterator rend() const;

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

   Throws: Nothing.

   Complexity: Constant.

10.     const_iterator cbegin() const;

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

    Throws: Nothing.

    Complexity: Constant.

11.     const_iterator cend() const;

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

    Throws: Nothing.

    Complexity: Constant.

12.     const_reverse_iterator crbegin() const;

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

    Throws: Nothing.

    Complexity: Constant.

13.     const_reverse_iterator crend() const;

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

    Throws: Nothing.

    Complexity: Constant.

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

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

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

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

18.     reference front();

    Requires: !empty()

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

    Throws: Nothing.

    Complexity: Constant.

19.     const_reference front() const;

    Requires: !empty()

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

    Throws: Nothing.

    Complexity: Constant.

20.     reference back();

    Requires: !empty()

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

    Throws: Nothing.

    Complexity: Constant.

21.     const_reference back() const;

    Requires: !empty()

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

    Throws: Nothing.

    Complexity: Constant.

22.     size_type size() const;

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

    Throws: Nothing.

    Complexity: Constant.

23.     size_type max_size() const;

    Effects: Returns the largest possible size of the deque.

    Throws: Nothing.

    Complexity: Constant.

24.     bool empty() const;

    Effects: Returns true if the deque contains no elements.

    Throws: Nothing.

    Complexity: Constant.

25.     void swap(deque & x);

    Effects: Swaps the contents of *this and x. If this->allocator_type() != x.allocator_type() allocators are also swapped.

    Throws: Nothing.

    Complexity: Constant.

26.     void assign(size_type n, const T & val);

    Effects: Assigns the n copies of val to *this.

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

    Complexity: Linear to n.

27.     template<typename InpIt> void assign(InpIt first, InpIt last);

    Effects: Assigns the the range [first, last) to *this.

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

    Complexity: Linear to n.

28.     void push_back(const T & x);

    Effects: Inserts a copy of x at the end of the deque.

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

    Complexity: Amortized constant time.

29.     void push_back(T && x);

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

    Throws: If memory allocation throws.

    Complexity: Amortized constant time.

30.     void push_front(const T & x);

    Effects: Inserts a copy of x at the front of the deque.

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

    Complexity: Amortized constant time.

31.     void push_front(T && x);

    Effects: Constructs a new element in the front of the deque and moves the resources of mx to this new element.

    Throws: If memory allocation throws.

    Complexity: Amortized constant time.

32.     void pop_back();

    Effects: Removes the last element from the deque.

    Throws: Nothing.

    Complexity: Constant time.

33.     void pop_front();

    Effects: Removes the first element from the deque.

    Throws: Nothing.

    Complexity: Constant time.

34.     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 x's copy constructor throws.

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

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

36.     void insert(const_iterator pos, size_type n, const value_type & 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.

37.     template<typename InpIt>
          void insert(const_iterator pos, InpIt first, InpIt 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 constructor throws.

    Complexity: Linear to std::distance [first, last).

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

    Throws: If memory allocation throws or the in-place constructor throws.

    Complexity: Amortized constant time

39.     template<class... Args> void emplace_front(Args &&... args);

    Effects: Inserts an object of type T constructed with std::forward<Args>(args)... in the beginning of the deque.

    Throws: If memory allocation throws or the in-place constructor throws.

    Complexity: Amortized constant time

40.     template<class... Args> iterator emplace(const_iterator p, 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.

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

41.     void resize(size_type new_size, const value_type & 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.

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

43.     iterator erase(const_iterator pos);

    Effects: Erases the element at position pos.

    Throws: Nothing.

    Complexity: Linear to the elements between pos and the last element (if pos is near the end) or the first element if(pos is near the beginning). Constant if pos is the first or the last element.

44.     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 the elements between pos and the last element (if pos is near the end) or the first element if(pos is near the beginning).

45.     void clear();

    Effects: Erases all the elements of the deque.

    Throws: Nothing.

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

46.     void shrink_to_fit();

    Effects: Tries to deallocate the excess of memory created with previous allocations. The size of the deque is unchanged

    Throws: If memory allocation throws.

    Complexity: Constant.