[#bsl-stack-05]
= xref:bsl.adoc[bsl]::stack
:relfileprefix: ../
:mrdocs:

This `class` defines a container adapter which supports access primarily via `push`, `pop`, and `top`. This type can be based on a variety of other container types, including `deque`, `vector`, and `list`. This type is value‐semantic if the supporting `CONTAINER` and `VALUE` are value‐semantic.

== Synopsis

Declared in `<bslstl_stack.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<
    class VALUE,
    class CONTAINER = xref:bsl/deque-0c.adoc[deque<VALUE>]>
class stack;
----

== Description

Note that we never use `VALUE` in the implementation except in the default argument of `CONTAINER`. We use `CONTAINER::value_type` for everything, which means that if `CONTAINER` is specified, then `VALUE` is ignored.

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:bsl/stack-05/const_reference.adoc[`const_reference`] 
| This `typedef` is an alias for `const_reference`.
| xref:bsl/stack-05/container_type.adoc[`container_type`] 
| This `typedef` is an alias for `container_type`.
| xref:bsl/stack-05/reference.adoc[`reference`] 
| This `typedef` is an alias for `reference`.
| xref:bsl/stack-05/size_type.adoc[`size_type`] 
| This `typedef` is an alias for `size_type`.
| xref:bsl/stack-05/value_type.adoc[`value_type`] 
| This `typedef` is an alias to `CONTAINER::value_type`.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/stack-05/2constructor-010.adoc[`stack`]         [.small]#[constructor]#
| Constructors
| xref:bsl/stack-05/operator_assign-0a.adoc[`operator=`] 
| Assignment operators
| xref:bsl/stack-05/emplace.adoc[`emplace`] 
| Push onto this stack a newly created `value_type` object constructed by forwarding `get_allocator()` (if required) and the specified (variable number of) `args` to the corresponding constructor of `value_type`. Return a reference providing modifiable access to the inserted element.
| xref:bsl/stack-05/empty.adoc[`empty`] 
| Return `true` if this stack contains no elements and `false` otherwise.
| xref:bsl/stack-05/pop.adoc[`pop`] 
| Remove the top element from this stack. The behavior is undefined if this stack is empty.
| xref:bsl/stack-05/push-08.adoc[`push`] 
| `push` overloads
| xref:bsl/stack-05/push_range.adoc[`push_range`] 
| Push onto this stack 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`.
| xref:bsl/stack-05/size.adoc[`size`] 
| Return the number of elements contained in this stack.
| xref:bsl/stack-05/swap.adoc[`swap`] 
| Exchange the value of this stack with the value of the specified `other` stack.
| xref:bsl/stack-05/top-06.adoc[`top`] 
| `top` overloads
| xref:bsl/stack-05/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<stack, UsesBslmaAllocator, BloombergLP::bslma::UsesBslmaAllocator<container_type>::value>`] 
| Declare nested type traits for this type.
|===


== Protected Data Members

[cols="1,4"]
|===
| Name| Description
| xref:bsl/stack-05/c.adoc[`c`] 
| The `c` data member.
|===


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/stack-0f.adoc[`stack<TYPE>`] 
| Deduce the template parameter `VALUE` from the parameters supplied to the constructor of `stack`.
| xref:bsl/stack-06f.adoc[`stack<TYPE, deque<TYPE, ALLOCATOR>>`] 
| Deduce the template parameters `VALUE` and `CONTAINER` from the parameters supplied to the constructor of `stack`. This deduction guide does not participate unless the `ALLOCATOR` parameter meets the requirements for a standard allocator.
| xref:bsl/stack-06c.adoc[`stack<t_TYPE, deque<t_TYPE, t_ALLOCATOR>>`] 
| Deduce the template parameters `VALUE` and `ALLOCATOR` from the parameters supplied to the constructor of `stack`. This deduction guide does not participate unless the `t_ALLOCATOR` parameter meets the requirements for a standard allocator.
| xref:bsl/stack-0c.adoc[`stack<CONTAINER::value_type, CONTAINER>`] 
| Deduce the template parameters `VALUE` and `CONTAINER` from the parameters supplied to the constructor of `stack`. This deduction guide does not participate if the parameter meets the requirements for a standard allocator.
| xref:bsl/stack-06b.adoc[`stack<CONTAINER::value_type, CONTAINER>`] 
| Deduce the template parameters `VALUE` and `CONTAINER` from the parameters supplied to the constructor of `stack`. This deduction guide does not participate unless the supplied allocator is convertible to the underlying container's `allocator_type`.
| xref:bsl/stack-01.adoc[`stack<ranges::range_value_t<t_RANGE>>`] 
| Deduce the template parameter `VALUE` from the parameters supplied to the constructor of `stack`.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:bsl/operator_3way-03e.adoc[bsl::operator<=>]`
| Same as the related overload above for `operator<=>`.
| `xref:bsl/operator_ge-0f.adoc[bsl::operator>=]`
| Same as the related overload above for `operator>=`.
| `xref:bsl/operator_le-0b.adoc[bsl::operator<=]`
| Return whether the specified stacks compare lexicographically; see the non‐member `operator<=` in the `bsl` namespace.
| `xref:bsl/operator_gt-017.adoc[bsl::operator>]`
| Return whether the specified stacks compare lexicographically; see the non‐member `operator>` in the `bsl` namespace.
| `xref:bsl/operator_lt-08.adoc[bsl::operator<]`
| Return whether the specified stacks compare lexicographically; see the non‐member `operator<` in the `bsl` namespace.
| `xref:bsl/operator_not_eq-03.adoc[bsl::operator!=]`
| Same as the related overload above for `operator!=`.
| `xref:bsl/operator_eq-00.adoc[bsl::operator==]`
| Same as the related overload above for `operator==`.
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/operator_not_eq-079.adoc[`operator!=`]
| Return `true` if the specified `lhs` and `rhs` objects do not have the same value, and `false` otherwise. Two `stack` objects `lhs` and `rhs` do not have the same value if they do not have the same number of elements, or some element in the ordered sequence of elements of `lhs` does not have the same value as the corresponding element in the ordered sequence of elements of `rhs`. This method requires that the (template parameter) type `VALUE` be `equality‐comparable` (see {Requirements on `VALUE`}).
| xref:bsl/operator_lt-0c.adoc[`operator<`]
| Return `true` if the value of the specified `lhs` stack is lexicographically less than that of the specified `rhs` stack, and `false` otherwise. Given iterators `i` and `j` over the respective sequences `[lhs.begin() .. lhs.end())]` and `[rhs.begin() .. rhs.end())]`, the value of stack `lhs` is lexicographically less than that of stack `rhs` if `true == *i < *j` for the first pair of corresponding iterator positions where `*i < *j` and `*j < *i` are not both `false`. If no such corresponding iterator position exists, the value of `lhs` is lexicographically less than that of `rhs` if `lhs.size() < rhs.size()`. This method requires that `operator<`, inducing a total order, be defined for `value_type`.
| xref:bsl/operator_le-0ec.adoc[`operator<=`]
| Return `true` if the value of the specified `lhs` stack is lexicographically less than or equal to that of the specified `rhs` stack, and `false` otherwise. The value of stack `lhs` is lexicographically less than or equal to that of stack `rhs` if `rhs` is not lexicographically less than `lhs` (see `operator<`). This method requires that `operator<`, inducing a total order, be defined for `value_type`. Note that this operator returns `!(rhs < lhs)`.
| xref:bsl/operator_3way-01d.adoc[`operator<=>`]
| Same as the related overload above for `operator<=>`.
| xref:bsl/operator_eq-0e3.adoc[`operator==`]
| Return `true` if the specified `lhs` and `rhs` objects have the same value, and `false` otherwise. Two `stack` 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` be `equality‐comparable` (see {Requirements on `VALUE`}).
| xref:bsl/operator_gt-00.adoc[`operator>`]
| Return `true` if the value of the specified `lhs` stack is lexicographically greater than that of the specified `rhs` stack, and `false` otherwise. The value of stack `lhs` is lexicographically greater than that of stack `rhs` if `rhs` is lexicographically less than `lhs` (see `operator<`). This method requires that `operator<`, inducing a total order, be defined for `value_type`. Note that this operator returns `rhs < lhs`.
| xref:bsl/operator_ge-0b.adoc[`operator>=`]
| Return `true` if the value of the specified `lhs` stack is lexicographically greater than or equal to that of the specified `rhs` stack, and `false` otherwise. The value of stack `lhs` is lexicographically greater than or equal to that of stack `rhs` if `lhs` is not lexicographically less than `rhs` (see `operator<`). This method requires that `operator<`, inducing a total order, be defined for `value_type`. Note that this operator returns `!(lhs < rhs)`.
| xref:bsl/swap-0cb.adoc[`swap`]
| Swap the value of the specified `lhs` stack with the value of the specified `rhs` stack.
|===


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