caution

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

Overview

Simplified

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

Detailed

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

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

The new interface is a FIFO (First In First Out) data structure. This means that the first element to be pushed is the first one to be accessed (like in a shop queue - first person to get in is the first person to be served).

Technical definition of a queue

The std::queue class is a container adapter that gives the programmer the functionality of a queue - specifically, a FIFO (first-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 queue pushes the elements on the back of the underlying container and pops them from the front.

std::queue

Defined in

queue

Template parameters

pub	T	The type of the stored elements. since C++17 danger The behaviour is undefined if T is not Container::value_type.
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 queue.
pub	(destructor)	Destructs a queue.
pub	operator=	Assigns one queue to another.

Element access

pub	front	Accesses the element at the top (first pushed).
pub	back	Accesses the element at the back (last pushed).

Capacity

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

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 queue.front()).
pub	swap (since C++11)	Swaps two queues.

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 queue.
pub	std::swap (std::queue)	An overload for the std::swap algorithm.

Helper classes

pub

std::uses_allocator (std::queue)

Specializes the std::uses_allocator type trait.

Deduction guides (since C++17)

Click to expand

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

// (2)
template< class Container, class Alloc >
queue( Container, Alloc )
  -> queue<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) (since C++23)
template< class InputIt >
queue( InputIt, InputIt )
  -> queue<typename std::iterator_traits<InputIt>::value_type>;

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

(3) and (4) allow deduction from a iterator range

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 (2) (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

Basic manipulation

Push and pop on queue, printing the values

#include <iostream>
#include <queue>

int main()
{
	std::priority_queue<int> q;

	queue.push(1);
	queue.push(2);
	queue.push(3);

	while (!queue.empty()) {
		std::cout << queue.top() << '\n';
		queue.pop();
	}
}

Result

1
2
3