caution

Note, this article is not finished! You can help by editing this doc page.

Stack class reference

Overview

Simplified

template< class T, /* ... */ >
class stack;

Detailed

template<
    class T,
    class Container = std::deque<T>
>
class stack;

Stack is a container adapter - it adapts a container by providing a new interface to it.

The new interface is a LIFO (Last In First Out) data structure. This means that the last element to be pushed is the first one to be accessed (like a plate stack - the last plate to be pushed on the top is the first one to be taken from it).

Technical definition of a stack

The std::stack class is a container adaptor that gives the programmer the functionality of a stack - specifically, a LIFO (last-in, first-out) data structure.

The class template acts as a wrapper to the underlying container - only a specific set of functions is provided. The stack pushes and pops the element from the back of the underlying container, known as the top of the stack.

std::stack

Defined in

queue

Template parameters

pub	T	The type of the stored elements. The behaviour is undefined if T is not Container::value_type. (since C++17)
pub	Container	The type of the underlying container used to store the elements. By default std::deque<T>. The container must satisfy SequenceContainer Additionally, it must provide the following functions with the usual semantics: back() front() push_back() pop_front() The standard containers std::deque and std::list satisfy these requirements.

Type names

pub	container_type	Container
pub	value_type	Container::value_type
pub	size_type	Container::size_type
pub	reference	Container::reference
pub	const_reference	Container::const_reference

Member functions

pub	(constructors)	Constructs a stack.
pub	(destructor)	Destructs a stack.
pub	operator=	Assigns one stack to another

Element access

pub

top

Accesses the element at the top (last pushed)

Capacity

pub	empty	Returns true if the stack is empty, otherwise false.
pub	size	Returns the number of elements in the stack.

Modifiers

pub	push	Inserts a new element at the end
pub	emplace (since C++11)	Constructs a new element in-place at the end
pub	pop	Removes the first pushed element (the one that would've been returned by stack.front()).
pub	swap (since C++11)	Swaps two stacks

Member objects

prot

Container c

The underlying container. By default std::deque<T>.

Non-member functions

pub	operator== operator!= operator< operator> operator<= operator>= operator<=> (C++20)	Lexicographically compares values in a stack.
pub	std::swap (std::stack)	An overload for the std::swap algorithm.

Helper classes

pub

std::uses_allocator (std::stack)

Specializes the std::uses_allocator type trait.

Deduction guides (since C++17)

Click to expand

// (1)
template< class Container >
stack( Container )
  -> stack<typename Container::value_type, Container>;

// (2) (since C++23)
template< class Container, class Alloc >
stack( Container, Alloc )
  -> stack<typename Container::value_type, Container>;

(1) and (2) allow deduction from an underlying container type

(2) uses std::deque<typename std::iterator_traits<InputIt>::value_type> as an underlying container type (see (4))

// (3)
template< class Container, class Alloc >
stack( Container, Alloc )
  -> stack<typename Container::value_type, Container>;

// (4) (since C++23)
template< class InputIt, class Alloc >
stack( InputIt, InputIt, Alloc )
  -> stack<typename std::iterator_traits<InputIt>::value_type,
    std::deque<typename std::iterator_traits<InputIt>::value_type, Alloc>>;

same as (1) and (2), except the allocator is provided

Overload resolution

In order for any of the deduction guides to participate in overload resolution, the folllowing requirements must be met:

• InputIt satisfies LegacyInputIterator
• Container doesn't satisfy Allocator
• for (3) (until C++23) and (4) (since C++23), Alloc satisfies Allocator
• std::uses_allocator_v<Container, Alloc> is true if both Container and Alloc exist.

note

The extent to which the library determines that a type does not satisfy LegacyInputIterator is unspecified, except that as a minimum:

• Integral types do not qualify as input iterators.

Likewise, the extent to which it determines that a type does not satisfy Allocator is unspecified, except that as a minimum:

• The member type Alloc::value_type must exist.
• The expression std::declval<Alloc&>().allocate(std::size_t{}) must be well-formed when treated as an unevaluated operand.

Examples

important

This section requires improvement. You can help by editing this doc page.