[#bsl-deque-0c]
= xref:bsl.adoc[bsl]::deque
:relfileprefix: ../
:mrdocs:

STL‐compliant double‐ended sequence container using the `bslma` model.

== Synopsis

Declared in `<bslstl_deque.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<
    class VALUE_TYPE,
    class ALLOCATOR = xref:bsl/allocator-0df.adoc[allocator<VALUE_TYPE>]>
class deque
    : public xref:bsl/Deque_Base.adoc[Deque_Base<VALUE_TYPE>]
----

== Description

This class template provides an STL‐compliant `deque` that conforms to the `bslma::Allocator` model. For the requirements of a deque class, consult the C++11 standard. In particular, this implementation offers the general rules that: 1. A call to any method that would result in a deque having a size greater than the value returned by `max_size` triggers a call to `bslstl::StdExceptUtil::throwLengthError`. 2. A call to an `at` method that attempts to access a position outside of the valid range of a deque triggers a call to `bslstl::StdExceptUtil::throwOutOfRange`.

Note that portions of the standard methods are implemented in `Deque_Base`, which is parameterized on only `VALUE_TYPE` in order to generate smaller debug strings.

This class: * supports a complete set of _value‐semantic_ operations ‐ except for `BDEX` serialization * is _exception‐neutral_ * is _alias‐safe_ * is `const` _thread‐safe_ For terminology see {`bsldoc_glossary`}.

In addition, the following members offer a full guarantee of rollback: if an exception is thrown during the invocation of `insert`, `push_front`, or `push_back` on a pre‐existing object, the object is left in a valid state and its value is unchanged.

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:bsl/Deque_Base.adoc[Deque_Base<VALUE_TYPE>]`
| Allocator‐independent layout and accessors shared by `deque`.
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:bsl/deque-0c/allocator_type.adoc[`allocator_type`] 
| This `typedef` is an alias to the (template parameter) `ALLOCATOR`.
| xref:bsl/deque-0c/const_iterator.adoc[`const_iterator`] 
| This `typedef` is an alias for `const_iterator`.
| xref:bsl/deque-0c/const_pointer.adoc[`const_pointer`] 
| This `typedef` is an alias for `const_pointer`.
| xref:bsl/deque-0c/const_reference.adoc[`const_reference`] 
| This `typedef` is an alias for `const_reference`.
| xref:bsl/deque-0c/const_reverse_iterator.adoc[`const_reverse_iterator`] 
| This `typedef` is an alias to `bsl::reverse_iterator<const_iterator>`.
| xref:bsl/deque-0c/difference_type.adoc[`difference_type`] 
| This `typedef` is an alias for `difference_type`.
| xref:bsl/deque-0c/iterator-02.adoc[`iterator`] 
| This `typedef` is an alias to `Iterator`.
| xref:bsl/deque-0c/pointer.adoc[`pointer`] 
| This `typedef` is an alias to `AllocatorTraits::pointer`.
| xref:bsl/deque-0c/reference.adoc[`reference`] 
| This `typedef` is an alias for `reference`.
| xref:bsl/deque-0c/reverse_iterator.adoc[`reverse_iterator`] 
| This `typedef` is an alias to `bsl::reverse_iterator<iterator>`.
| xref:bsl/deque-0c/size_type.adoc[`size_type`] 
| This `typedef` is an alias for `size_type`.
| xref:bsl/deque-0c/value_type.adoc[`value_type`] 
| This `typedef` is an alias for `value_type`.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/deque-0c/2constructor-0f62.adoc[`deque`]         [.small]#[constructor]#
| Constructors
| xref:bsl/deque-0c/2destructor.adoc[`~deque`] [.small]#[destructor]#
| Destroy this object.
| xref:bsl/deque-0c/operator_assign-05f.adoc[`operator=`] 
| Assignment operators
| xref:bsl/deque-0c/append_range.adoc[`append_range`] 
| Append the elements of `range` to the back of this deque.
| xref:bsl/deque-0c/assign-0e.adoc[`assign`] 
| `assign` overloads
| xref:bsl/deque-0c/assign_range.adoc[`assign_range`] 
| Assign to this deque the elements of `range`.
| xref:bsl/Deque_Base/at-04.adoc[`at`] 
| `at` overloads
| xref:bsl/Deque_Base/back-06.adoc[`back`] 
| `back` overloads
| xref:bsl/Deque_Base/begin-0fd.adoc[`begin`] 
| `begin` overloads
| xref:bsl/Deque_Base/capacity.adoc[`capacity`] 
| Return how many end insertions remain before iterators are invalidated.
| xref:bsl/Deque_Base/cbegin.adoc[`cbegin`] 
| Return an iterator providing non‐modifiable access to the first element in this deque, and the past‐the‐end iterator if this deque is empty.
| xref:bsl/Deque_Base/cend.adoc[`cend`] 
| Return the past‐the‐end (forward) iterator providing non‐modifiable access to this deque.
| xref:bsl/deque-0c/clear.adoc[`clear`] 
| Remove all elements from this deque, leaving its capacity unchanged.
| xref:bsl/Deque_Base/crbegin.adoc[`crbegin`] 
| Return a reverse iterator providing non‐modifiable access to the last element in this deque, and the past‐the‐end reverse iterator if this deque is empty.
| xref:bsl/Deque_Base/crend.adoc[`crend`] 
| Return the past‐the‐end reverse iterator providing non‐modifiable access to this deque.
| xref:bsl/deque-0c/emplace.adoc[`emplace`] 
| Emplace a newly constructed element before `position`.
| xref:bsl/deque-0c/emplace_back.adoc[`emplace_back`] 
| Emplace a newly constructed element at the back of this deque.
| xref:bsl/deque-0c/emplace_front.adoc[`emplace_front`] 
| Emplace a newly constructed element at the front of this deque.
| xref:bsl/Deque_Base/empty.adoc[`empty`] 
| Return `true` if this deque contains no elements, and `false` otherwise.
| xref:bsl/Deque_Base/end-01.adoc[`end`] 
| `end` overloads
| xref:bsl/deque-0c/erase-0f.adoc[`erase`] 
| `erase` overloads
| xref:bsl/Deque_Base/front-04.adoc[`front`] 
| `front` overloads
| xref:bsl/deque-0c/get_allocator.adoc[`get_allocator`] 
| Return the allocator used by this deque to supply memory.
| xref:bsl/deque-0c/insert-07.adoc[`insert`] 
| `insert` overloads
| xref:bsl/deque-0c/insert_range.adoc[`insert_range`] 
| Insert the elements of `range` before `position`.
| xref:bsl/deque-0c/max_size.adoc[`max_size`] 
| Return the theoretical maximum size of this deque.
| xref:bsl/Deque_Base/operator_subs-09.adoc[`operator[]`] 
| Subscript operators
| xref:bsl/deque-0c/pop_back.adoc[`pop_back`] 
| Erase the last element from this deque. The behavior is undefined if this deque is empty.
| xref:bsl/deque-0c/pop_front.adoc[`pop_front`] 
| Erase the first element from this deque. The behavior is undefined if this deque is empty.
| xref:bsl/deque-0c/prepend_range.adoc[`prepend_range`] 
| Prepend the elements of `range` to the front of this deque.
| xref:bsl/deque-0c/push_back-0f.adoc[`push_back`] 
| `push_back` overloads
| xref:bsl/deque-0c/push_front-0e.adoc[`push_front`] 
| `push_front` overloads
| xref:bsl/Deque_Base/rbegin-09.adoc[`rbegin`] 
| `rbegin` overloads
| xref:bsl/Deque_Base/rend-02.adoc[`rend`] 
| `rend` overloads
| xref:bsl/deque-0c/reserve.adoc[`reserve`] 
| Ensure capacity for `numElements` pushes without invalidating iterators.
| xref:bsl/deque-0c/resize-04.adoc[`resize`] 
| `resize` overloads
| xref:bsl/deque-0c/shrink_to_fit.adoc[`shrink_to_fit`] 
| Minimize unused capacity without moving contained elements.
| xref:bsl/Deque_Base/size.adoc[`size`] 
| Return the number of elements contained by this deque.
| xref:bsl/deque-0c/swap.adoc[`swap`] 
| Exchange the value of this deque with that of `other`.
|===


== Protected Data Members

[cols="1,4"]
|===
| Name| Description
| xref:bsl/Deque_Base/d_blocksLength.adoc[`d_blocksLength`] 
| Length of the `d_blocks_p` array.
| xref:bsl/Deque_Base/d_blocks_p.adoc[`d_blocks_p`] 
| Array of pointers to blocks (owned).
| xref:bsl/Deque_Base/d_finish.adoc[`d_finish`] 
| The `d_finish` data member.
| xref:bsl/Deque_Base/d_start.adoc[`d_start`] 
| The `d_start` data member.
|===


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/deque-017.adoc[`deque<VALUE>`] 
| Deduce the template parameter `VALUE` from the `value_type` of the iterators supplied to the constructor of `deque`.
| xref:bsl/deque-01a.adoc[`deque<VALUE>`] 
| Deduce `VALUE` from an initializer‐list constructor argument.
| xref:bsl/deque-05f.adoc[`deque<VALUE>`] 
| Deduce `VALUE` from iterator pair constructor arguments.
| xref:bsl/deque-04.adoc[`deque<VALUE>`] 
| Deduce `VALUE` from size/value constructor arguments.
| xref:bsl/deque-00.adoc[`deque<VALUE, ALLOCATOR>`] 
| Deduce `VALUE` and `ALLOCATOR` from iterator‐pair construction.
| xref:bsl/deque-05e.adoc[`deque<ranges::range_value_t<t_RANGE>, t_ALLOCATOR>`] 
| Deduce the template parameters `VALUE_TYPE` and `ALLOCATOR` from the parameters supplied to the constructor of `deque`.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:bsl/Deque_Guard.adoc[bsl::Deque_Guard]`
| Proctor for uncommitted elements constructed at one end of a deque.
| `xref:bsl/Deque_BlockProctor.adoc[bsl::Deque_BlockProctor]`
| Proctor that deallocates empty blocks at one end of a deque.
| `xref:bsl/Deque_BlockCreator.adoc[bsl::Deque_BlockCreator]`
| Helper that allocates tentative blocks at either end of a deque.
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/erase-082.adoc[`erase`]
| Erase every element of `deq` that compares equal to `value`.
| xref:bsl/erase_if-0b.adoc[`erase_if`]
| Erase every element of `deq` that satisfies `predicate`.
| xref:bsl/operator_3way-07cc.adoc[`operator<=>`]
| Perform a lexicographic three‐way comparison of `lhs` and `rhs`.
| xref:bsl/operator_eq-0ce.adoc[`operator==`]
| Return `true` if `lhs` and `rhs` have the same value.
| xref:bsl/swap-096.adoc[`swap`]
| Exchange the values of the specified `a` and `b` deques.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#