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.

Synopsis

Declared in <bslstl_deque.h>

template<
    class VALUE_TYPE,
    class ALLOCATOR = allocator<VALUE_TYPE>>
class deque
    : public Deque_Base<VALUE_TYPE>

Description

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

Name

Description

Deque_Base<VALUE_TYPE>

This class describes the basic layout for a deque class. It is important that this class has the same layout as the deque class implementation. It is parameterized by VALUE_TYPE only and implements the portion of bsl::deque that does not need to know about its (template parameter) type ALLOCATOR (in order to generate shorter debug strings). Note that this class must have the same layout as Deque_Imp (see implementation file).

Type Aliases

Name

Description

allocator_type

This typedef is an alias to the (template parameter) ALLOCATOR.

const_iterator

This typedef is an alias for const_iterator.

const_pointer

This typedef is an alias for const_pointer.

const_reference

This typedef is an alias for const_reference.

const_reverse_iterator

This typedef is an alias to bsl::reverse_iterator<const_iterator>.

difference_type

This typedef is an alias for difference_type.

iterator

This typedef is an alias to Iterator.

pointer

This typedef is an alias to AllocatorTraits::pointer.

reference

This typedef is an alias for reference.

reverse_iterator

This typedef is an alias to bsl::reverse_iterator<iterator>.

size_type

This typedef is an alias for size_type.

value_type

This typedef is an alias for value_type.

Member Functions

Name

Description

deque [constructor]

Constructors

~deque [destructor]

Destroy this object.

operator=

Assignment operators

append_range

Append to the end of this object the elements of the specified range. Note that range must meet the requirements of an input range and the values from range must have a type matching or convertible to (template parameter) VALUE_TYPE.

assign

assign overloads

assign_range

Assign to this object the elements of the specified range. Note that range must meet the requirements of an input range and the values from range must have a type matching or convertible to (template parameter) VALUE_TYPE.

at

at overloads

back

back overloads

begin

begin overloads

capacity

Return the sum of the current size of this deque plus the minimum number of push_front or push_back operations needed to invalidate iterators in this deque. Note that this method is not part of the C++ standard.

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.

cend

Return the past‐the‐end (forward) iterator providing non‐modifiable access to this deque.

clear

Remove all elements from this deque making its size 0. Note that although this deque is empty after this method returns, it preserves the same capacity it had before the method was called.

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.

crend

Return the past‐the‐end reverse iterator providing non‐modifiable access to this deque.

emplace

Insert at the specified position in this deque a newly created value_type object, constructed by forwarding get_allocator() (if required) and the specified (variable number of) arguments to the corresponding constructor of value_type, and return an iterator providing modifiable access to the newly created and inserted element. If an exception is thrown (other than by the copy constructor, move constructor, assignment operator, or move assignment operator of value_type), this method has no effect. This method requires that the (template parameter) VALUE_TYPE be move‐insertable into this deque and emplace‐constructible from arguments (see {Requirements on VALUE_TYPE}). The behavior is undefined unless position is an iterator in the range [cbegin() .. cend()] (both endpoints included).

emplace_back

Append to the back of this deque a newly created value_type object, constructed by forwarding get_allocator() (if required) and the specified (variable number of) arguments to the corresponding constructor of value_type. Return a reference providing modifiable access to the inserted element. If an exception is thrown (other than by the move constructor of a non‐copy‐insertable value_type), this method has no effect. This method requires that the (template parameter) VALUE_TYPE be move‐insertable into this deque and emplace‐constructible from arguments (see {Requirements on VALUE_TYPE}).

emplace_front

Prepend to the front of this deque a newly created value_type object, constructed by forwarding get_allocator() (if required) and the specified (variable number of) arguments to the corresponding constructor of value_type. Return a reference providing modifiable access to the inserted element. If an exception is thrown (other than by the move constructor of a non‐copy‐insertable value_type), this method has no effect. This method requires that the (template parameter) VALUE_TYPE be move‐insertable into this deque and emplace‐constructible from arguments (see {Requirements on VALUE_TYPE}).

empty

Return true if this deque contains no elements, and false otherwise.

end

end overloads

erase

erase overloads

front

front overloads

get_allocator

Return the allocator used by this deque to supply memory.

insert

insert overloads

insert_range

Insert at the specified position in this object the elements of the specified range. Note that range must meet the requirements of an input range and the values from range must have a type matching or convertible to (template parameter) VALUE_TYPE.

max_size

Return the maximum possible size of this deque. Note that this is a theoretical maximum (such as the maximum value that can be held by size_type). Also note that any request to create or enlarge a deque to a size greater than max_size() is guaranteed to raise a bsl::length_error exception.

operator[]

Subscript operators

pop_back

Erase the last element from this deque. The behavior is undefined if this deque is empty.

pop_front

Erase the first element from this deque. The behavior is undefined if this deque is empty.

prepend_range

Prepend to the front of this object the elements of the specified range. Note that range must meet the requirements of an input range and the values from range must have a type matching or convertible to (template parameter) VALUE_TYPE.

push_back

push_back overloads

push_front

push_front overloads

rbegin

rbegin overloads

rend

rend overloads

reserve

Change the capacity of this deque such that, after this method returns, iterators remain valid provided that no more than the specified numElements objects are pushed to the front or back of the deque after this call. If it is already possible to push numElements objects to either end of this deque without invalidating iterators, this method has no effect. Note that inserting elements into the deque may still incur memory allocation. Also note that this method, if it has any effect, will invalidate iterators initialized prior to the call. Also note that this method is not part of the C++ standard.

resize

resize overloads

shrink_to_fit

Minimize the memory used by this deque to the extent possible without moving any contained elements. If an exception is thrown, the value of this object is unchanged. Note that this method has no effect on the memory used by individual elements of the (template parameter) VALUE_TYPE.

size

Return the number of elements contained by this deque.

swap

Exchange the value of this object with that of the specified other object; also exchange the allocator of this object with that of other if the (template parameter) type ALLOCATOR has the propagate_on_container_swap trait, and do not modify either allocator otherwise. This method provides the no‐throw exception‐safety guarantee. This operation has O[1] complexity if either this object was created with the same allocator as other or ALLOCATOR has the propagate_on_container_swap trait; otherwise, it has O[n + m] complexity, where n and m are the number of elements in this object and other, respectively. Note that this method`s support for swapping objects created with different allocators when ALLOCATOR does not have the propagate_on_container_swap trait is a departure from the C++ Standard.

Protected Data Members

Name

Description

d_blocksLength

Length of the d_blocks_p array.

d_blocks_p

Array of pointers to blocks (owned).

d_finish

The d_finish data member.

d_start

The d_start data member.

Deduction Guides

Name

Description

deque<VALUE>

Deduce the template parameter VALUE from the value_type of the iterators supplied to the constructor of deque.

deque<VALUE>

Deduce the template parameter VALUE from the value_type of the initializer_list supplied to the constructor of deque. This deduction guide does not participate unless the supplied allocator is convertible to bsl::allocator<VALUE>.

deque<VALUE>

Deduce the template parameter VALUE from the value_type of the iterators supplied to the constructor of deque. This deduction guide does not participate unless the supplied allocator is convertible to bsl::allocator<VALUE>.

deque<VALUE>

Deduce the template parameter VALUE from the corresponding parameter supplied to the constructor of deque. This deduction guide does not participate unless the supplied allocator is convertible to bsl::allocator<VALUE>.

deque<VALUE, ALLOCATOR>

Deduce the template parameter VALUE from the value_type of the iterators supplied to the constructor of deque. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.

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

Name

Description

bsl::Deque_Guard

This class provides a proctor that maintains a count of the number of elements constructed at the front or back of a deque, but not yet committed to the deque's range of valid elements; if the count is non‐zero at destruction, the destructor destroys the elements in the range [d_deque_p‐>end() .. d_deque_p‐>end() + d_count)], or the range [d_deque_p‐>begin() ‐ d_count .. d_deque_p‐>begin())], depending on whether this proctor guards the back or front. This guard is used to undo element constructors in the event of an exception. It is up to the client code to increment the count whenever a new element is constructed and to decrement the count whenever d_start or d_finish of the guarded deque is moved to incorporate more elements.

bsl::Deque_BlockProctor

This class implements a proctor that, upon destruction and unless its release method has previously been invoked, deallocates empty blocks at one end (i.e., front or back) of a proctored deque. The end at which empty blocks are to be proctored is indicated by a flag supplied at construction. See emplace for a use case.

bsl::Deque_BlockCreator

This class allocates blocks at the front or back of a deque and tentatively adds them to the deque. It also keeps track of how many of the newly allocated blocks have actually been used by the deque. The destructor automatically frees any unused blocks (e.g., in case an exception is thrown).

Non-Member Functions

Name

Description

erase

Erase all the elements in the specified deque deq that compare equal to the specified value. Return the number of elements erased.

erase_if

Erase all the elements in the specified deque deq that satisfy the specified predicate predicate. Return the number of elements erased.

operator<=>

Perform a lexicographic three‐way comparison of the specified lhs and the specified rhs containers by using the comparison operators of VALUE_TYPE on each element; return the result of that comparison.

operator==

Return true if the specified lhs and rhs objects have the same value, and false otherwise. Two deque objects lhs and rhs have the same value if they have the same number of elements, and each element in the ordered sequence of elements of lhs has the same value as the corresponding element in the ordered sequence of elements of rhs. This method requires that the (template parameter) type VALUE_TYPE be equality‐comparable (see {Requirements on VALUE_TYPE}).

swap

Exchange the value of the specified a object with that of the specified b object; also exchange the allocator of a with that of b if the (template parameter) type ALLOCATOR has the propagate_on_container_swap trait, and do not modify either allocator otherwise. This function provides the no‐throw exception‐safety guarantee. This operation has O[1] complexity if either a was created with the same allocator as b or ALLOCATOR has the propagate_on_container_swap trait; otherwise, it has O[n + m] complexity, where n and m are the number of elements in a and b, respectively. Note that this function`s support for swapping objects created with different allocators when ALLOCATOR does not have the propagate_on_container_swap trait is a departure from the C++ Standard.

Created with MrDocs