Namespaces
Variants
Views
Actions

std::deque

From cppreference.com
< cpp‎ | container
Defined in header <deque>
template<

    class T,
    class Allocator = std::allocator<T>

> class deque;
(1)
namespace pmr {

    template <class T>
    using deque = std::deque<T, std::polymorphic_allocator<T>>;

}
(2) (since C++17)

std::deque (double-ended queue) is an indexed sequence container that allows fast insertion and deletion at both its beginning and its end. In addition, insertion and deletion at either end of a deque never invalidates pointers or references to the rest of the elements.

As opposed to std::vector, the elements of a deque are not stored contiguously: typical implementations use a sequence of individually allocated fixed-size arrays.

The storage of a deque is automatically expanded and contracted as needed. Expansion of a deque is cheaper than the expansion of a std::vector because it does not involve copying of the existing elements to a new memory location.

The complexity (efficiency) of common operations on deques is as follows:

  • Random access - constant O(1)
  • Insertion or removal of elements at the end or beginning - constant O(1)
  • Insertion or removal of elements - linear O(n)

std::deque meets the requirements of Container, AllocatorAwareContainer, SequenceContainer and ReversibleContainer.

Contents

[edit] Template parameters

T - The type of the elements.
T must meet the requirements of CopyAssignable and CopyConstructible. (until C++11)
The requirements that are imposed on the elements depend on the actual operations performed on the container. Generally, it is required that element type is a complete type and meets the requirements of Erasable, but many member functions impose stricter requirements. (since C++11)

[edit]

Allocator - An allocator that is used to acquire memory to store the elements. The type must meet the requirements of Allocator. The behavior is undefined if Allocator::value_type is not the same as T. [edit]

[edit] Iterator invalidation

There are still a few inaccuracies in this section, refer to individual member function pages for more detail

Operations Invalidated
All read only operations Never
swap, std::swap The past-the-end iterator may be invalidated (implementation defined)
shrink_to_fit, clear, insert, emplace, push_front, push_back, emplace_front, emplace_back Always
erase If erasing at begin - only erased elements

If erasing at end - only erased elements and the past-the-end iterator
Otherwise - all iterators are invalidated (including the past-the-end iterator).

resize If the new size is smaller than the old one : only erased elements and the past-the-end iterator

If the new size is bigger than the old one : all iterators are invalidated
Otherwise - none iterators are invalidated.

pop_front Only to the element erased
pop_back Only to the element erased and the past-the-end iterator

[edit] Notes

  • When inserting at either end of the deque, references are not invalidated by insert and emplace.
  • push_front, push_back, emplace_front and emplace_back do not invalidate any references to elements of the deque.
  • When erasing at either end of the deque, references to non-erased elements are not invalidated by erase, pop_front and pop_back.
  • A call to resize with a smaller size does not invalidate any references to non-erased elements.
  • A call to resize with a bigger size does not invalidate any references to elements of the deque.

[edit] Member types

Member type Definition
value_type T [edit]
allocator_type Allocator [edit]
size_type Unsigned integer type (usually std::size_t) [edit]
difference_type Signed integer type (usually std::ptrdiff_t) [edit]
reference
Allocator::reference (until C++11)
value_type& (since C++11)
[edit]
const_reference
Allocator::const_reference (until C++11)
const value_type& (since C++11)
[edit]
pointer
Allocator::pointer (until C++11)
std::allocator_traits<Allocator>::pointer (since C++11)
[edit]
const_pointer
Allocator::const_pointer (until C++11)
std::allocator_traits<Allocator>::const_pointer (since C++11)
[edit]
iterator RandomAccessIterator [edit]
const_iterator Constant random access iterator [edit]
reverse_iterator std::reverse_iterator<iterator> [edit]
const_reverse_iterator std::reverse_iterator<const_iterator> [edit]

[edit] Member functions

constructs the deque
(public member function) [edit]
destructs the deque
(public member function) [edit]
assigns values to the container
(public member function) [edit]
assigns values to the container
(public member function) [edit]
returns the associated allocator
(public member function) [edit]
Element access
access specified element with bounds checking
(public member function) [edit]
access specified element
(public member function) [edit]
access the first element
(public member function) [edit]
access the last element
(public member function) [edit]
Iterators
returns an iterator to the beginning
(public member function) [edit]
returns an iterator to the end
(public member function) [edit]
returns a reverse iterator to the beginning
(public member function) [edit]
returns a reverse iterator to the end
(public member function) [edit]
Capacity
checks whether the container is empty
(public member function) [edit]
returns the number of elements
(public member function) [edit]
returns the maximum possible number of elements
(public member function) [edit]
reduces memory usage by freeing unused memory
(public member function) [edit]
Modifiers
clears the contents
(public member function) [edit]
inserts elements
(public member function) [edit]
(C++11)
constructs element in-place
(public member function) [edit]
erases elements
(public member function) [edit]
adds an element to the end
(public member function) [edit]
constructs an element in-place at the end
(public member function) [edit]
removes the last element
(public member function) [edit]
inserts an element to the beginning
(public member function) [edit]
constructs an element in-place at the beginning
(public member function) [edit]
removes the first element
(public member function) [edit]
changes the number of elements stored
(public member function) [edit]
swaps the contents
(public member function) [edit]

[edit] Non-member functions

lexicographically compares the values in the deque
(function template) [edit]
specializes the std::swap algorithm
(function template) [edit]

[edit] Example

#include <iostream>
#include <deque>
 
int main()
{
    // Create a deque containing integers
    std::deque<int> d = {7, 5, 16, 8};
 
    // Add an integer to the beginning and end of the deque
    d.push_front(13);
    d.push_back(25);
 
    // Iterate and print values of deque
    for(int n : d) {
        std::cout << n << '\n';
    }
}

Output:

13
7
5
16
8
25