22 Containers library [containers]

22.6 Container adaptors [container.adaptors]

22.6.1 In general [container.adaptors.general]

1
#
The headers <queue> and <stack> define the container adaptors queue, priority_­queue, and stack.
2
#
The container adaptors each take a Container template parameter, and each constructor takes a Container reference argument.
This container is copied into the Container member of each adaptor.
If the container takes an allocator, then a compatible allocator may be passed in to the adaptor's constructor.
Otherwise, normal copy or move construction is used for the container argument.
The first template parameter T of the container adaptors shall denote the same type as Container​::​value_­type.
3
#
For container adaptors, no swap function throws an exception unless that exception is thrown by the swap of the adaptor's Container or Compare object (if any).
4
#
A constructor template of a container adaptor shall not participate in overload resolution if it has an InputIterator template parameter and a type that does not qualify as an input iterator is deduced for that parameter.
5
#
A deduction guide for a container adaptor shall not participate in overload resolution if any of the following are true:
  • (5.1)
    It has an InputIterator template parameter and a type that does not qualify as an input iterator is deduced for that parameter.
  • (5.2)
    It has a Compare template parameter and a type that qualifies as an allocator is deduced for that parameter.
  • (5.3)
    It has a Container template parameter and a type that qualifies as an allocator is deduced for that parameter.
  • (5.4)
    It has no Container template parameter, and it has an Allocator template parameter, and a type that does not qualify as an allocator is deduced for that parameter.
  • (5.5)
    It has both Container and Allocator template parameters, and uses_­allocator_­v<Container, Allocator> is false.
6
#
The exposition-only alias template iter-value-type defined in [sequences.general] may appear in deduction guides for container adaptors.

22.6.2 Header <queue> synopsis [queue.syn]

🔗
#include <compare> // see [compare.syn] #include <initializer_list> // see [initializer.list.syn] namespace std { template<class T, class Container = deque<T>> class queue; template<class T, class Container> bool operator==(const queue<T, Container>& x, const queue<T, Container>& y); template<class T, class Container> bool operator!=(const queue<T, Container>& x, const queue<T, Container>& y); template<class T, class Container> bool operator< (const queue<T, Container>& x, const queue<T, Container>& y); template<class T, class Container> bool operator> (const queue<T, Container>& x, const queue<T, Container>& y); template<class T, class Container> bool operator<=(const queue<T, Container>& x, const queue<T, Container>& y); template<class T, class Container> bool operator>=(const queue<T, Container>& x, const queue<T, Container>& y); template<class T, three_­way_­comparable Container> compare_three_way_result_t<Container> operator<=>(const queue<T, Container>& x, const queue<T, Container>& y); template<class T, class Container> void swap(queue<T, Container>& x, queue<T, Container>& y) noexcept(noexcept(x.swap(y))); template<class T, class Container, class Alloc> struct uses_allocator<queue<T, Container>, Alloc>; template<class T, class Container = vector<T>, class Compare = less<typename Container::value_type>> class priority_queue; template<class T, class Container, class Compare> void swap(priority_queue<T, Container, Compare>& x, priority_queue<T, Container, Compare>& y) noexcept(noexcept(x.swap(y))); template<class T, class Container, class Compare, class Alloc> struct uses_allocator<priority_queue<T, Container, Compare>, Alloc>; }

22.6.3 Header <stack> synopsis [stack.syn]

🔗
#include <compare> // see [compare.syn] #include <initializer_list> // see [initializer.list.syn] namespace std { template<class T, class Container = deque<T>> class stack; template<class T, class Container> bool operator==(const stack<T, Container>& x, const stack<T, Container>& y); template<class T, class Container> bool operator!=(const stack<T, Container>& x, const stack<T, Container>& y); template<class T, class Container> bool operator< (const stack<T, Container>& x, const stack<T, Container>& y); template<class T, class Container> bool operator> (const stack<T, Container>& x, const stack<T, Container>& y); template<class T, class Container> bool operator<=(const stack<T, Container>& x, const stack<T, Container>& y); template<class T, class Container> bool operator>=(const stack<T, Container>& x, const stack<T, Container>& y); template<class T, three_­way_­comparable Container> compare_three_way_result_t<Container> operator<=>(const stack<T, Container>& x, const stack<T, Container>& y); template<class T, class Container> void swap(stack<T, Container>& x, stack<T, Container>& y) noexcept(noexcept(x.swap(y))); template<class T, class Container, class Alloc> struct uses_allocator<stack<T, Container>, Alloc>; }

22.6.4 Class template queue [queue]

22.6.4.1 Definition [queue.defn]

1
#
Any sequence container supporting operations front(), back(), push_­back() and pop_­front() can be used to instantiate queue.
In particular, list and deque can be used.
namespace std { template<class T, class Container = deque<T>> class queue { public: using value_type = typename Container::value_type; using reference = typename Container::reference; using const_reference = typename Container::const_reference; using size_type = typename Container::size_type; using container_type = Container; protected: Container c; public: queue() : queue(Container()) {} explicit queue(const Container&); explicit queue(Container&&); template<class InputIterator> queue(InputIterator first, InputIterator last); template<class Alloc> explicit queue(const Alloc&); template<class Alloc> queue(const Container&, const Alloc&); template<class Alloc> queue(Container&&, const Alloc&); template<class Alloc> queue(const queue&, const Alloc&); template<class Alloc> queue(queue&&, const Alloc&); template<class InputIterator, class Alloc> queue(InputIterator first, InputIterator last, const Alloc&); [[nodiscard]] bool empty() const { return c.empty(); } size_type size() const { return c.size(); } reference front() { return c.front(); } const_reference front() const { return c.front(); } reference back() { return c.back(); } const_reference back() const { return c.back(); } void push(const value_type& x) { c.push_back(x); } void push(value_type&& x) { c.push_back(std::move(x)); } template<class... Args> decltype(auto) emplace(Args&&... args) { return c.emplace_back(std::forward<Args>(args)...); } void pop() { c.pop_front(); } void swap(queue& q) noexcept(is_nothrow_swappable_v<Container>) { using std::swap; swap(c, q.c); } }; template<class Container> queue(Container) -> queue<typename Container::value_type, Container>; template<class InputIterator> queue(InputIterator, InputIterator) -> queue<iter-value-type<InputIterator>>; template<class Container, class Allocator> queue(Container, Allocator) -> queue<typename Container::value_type, Container>; template<class InputIterator, class Allocator> queue(InputIterator, InputIterator, Allocator) -> queue<iter-value-type<InputIterator>, deque<iter-value-type<InputIterator>, Allocator>>; template<class T, class Container, class Alloc> struct uses_allocator<queue<T, Container>, Alloc> : uses_allocator<Container, Alloc>::type { }; }

22.6.4.2 Constructors [queue.cons]

🔗
explicit queue(const Container& cont);
1
#
Effects: Initializes c with cont.
🔗
explicit queue(Container&& cont);
2
#
Effects: Initializes c with std​::​move(cont).
🔗
template<class InputIterator> queue(InputIterator first, InputIterator last);
3
#
Effects: Initializes c with first as the first argument and last as the second argument.

22.6.4.3 Constructors with allocators [queue.cons.alloc]

1
#
If uses_­allocator_­v<container_­type, Alloc> is false the constructors in this subclause shall not participate in overload resolution.
🔗
template<class Alloc> explicit queue(const Alloc& a);
2
#
Effects: Initializes c with a.
🔗
template<class Alloc> queue(const container_type& cont, const Alloc& a);
3
#
Effects: Initializes c with cont as the first argument and a as the second argument.
🔗
template<class Alloc> queue(container_type&& cont, const Alloc& a);
4
#
Effects: Initializes c with std​::​move(cont) as the first argument and a as the second argument.
🔗
template<class Alloc> queue(const queue& q, const Alloc& a);
5
#
Effects: Initializes c with q.c as the first argument and a as the second argument.
🔗
template<class Alloc> queue(queue&& q, const Alloc& a);
6
#
Effects: Initializes c with std​::​move(q.c) as the first argument and a as the second argument.
🔗
template<class InputIterator, class Alloc> queue(InputIterator first, InputIterator last, const Alloc& alloc);
7
#
Effects: Initializes c with first as the first argument, last as the second argument, and alloc as the third argument.

22.6.4.4 Operators [queue.ops]

🔗
template<class T, class Container> bool operator==(const queue<T, Container>& x, const queue<T, Container>& y);
1
#
Returns: x.c == y.c.
🔗
template<class T, class Container> bool operator!=(const queue<T, Container>& x, const queue<T, Container>& y);
2
#
Returns: x.c != y.c.
🔗
template<class T, class Container> bool operator< (const queue<T, Container>& x, const queue<T, Container>& y);
3
#
Returns: x.c < y.c.
🔗
template<class T, class Container> bool operator> (const queue<T, Container>& x, const queue<T, Container>& y);
4
#
Returns: x.c > y.c.
🔗
template<class T, class Container> bool operator<=(const queue<T, Container>& x, const queue<T, Container>& y);
5
#
Returns: x.c <= y.c.
🔗
template<class T, class Container> bool operator>=(const queue<T, Container>& x, const queue<T, Container>& y);
6
#
Returns: x.c >= y.c.
🔗
template<class T, three_­way_­comparable Container> compare_three_way_result_t<Container> operator<=>(const queue<T, Container>& x, const queue<T, Container>& y);
7
#
Returns: x.c <=> y.c.

22.6.4.5 Specialized algorithms [queue.special]

🔗
template<class T, class Container> void swap(queue<T, Container>& x, queue<T, Container>& y) noexcept(noexcept(x.swap(y)));
1
#
Constraints: is_­swappable_­v<Container> is true.
2
#
Effects: As if by x.swap(y).

22.6.5 Class template priority_­queue [priority.queue]

22.6.5.1 Overview [priqueue.overview]

1
#
Any sequence container with random access iterator and supporting operations front(), push_­back() and pop_­back() can be used to instantiate priority_­queue.
In particular, vector and deque can be used.
Instantiating priority_­queue also involves supplying a function or function object for making priority comparisons; the library assumes that the function or function object defines a strict weak ordering.
namespace std { template<class T, class Container = vector<T>, class Compare = less<typename Container::value_type>> class priority_queue { public: using value_type = typename Container::value_type; using reference = typename Container::reference; using const_reference = typename Container::const_reference; using size_type = typename Container::size_type; using container_type = Container; using value_compare = Compare; protected: Container c; Compare comp; public: priority_queue() : priority_queue(Compare()) {} explicit priority_queue(const Compare& x) : priority_queue(x, Container()) {} priority_queue(const Compare& x, const Container&); priority_queue(const Compare& x, Container&&); template<class InputIterator> priority_queue(InputIterator first, InputIterator last, const Compare& x = Compare()); template<class InputIterator> priority_queue(InputIterator first, InputIterator last, const Compare& x, const Container&); template<class InputIterator> priority_queue(InputIterator first, InputIterator last, const Compare& x, Container&&); template<class Alloc> explicit priority_queue(const Alloc&); template<class Alloc> priority_queue(const Compare&, const Alloc&); template<class Alloc> priority_queue(const Compare&, const Container&, const Alloc&); template<class Alloc> priority_queue(const Compare&, Container&&, const Alloc&); template<class Alloc> priority_queue(const priority_queue&, const Alloc&); template<class Alloc> priority_queue(priority_queue&&, const Alloc&); template<class InputIterator, class Alloc> priority_queue(InputIterator, InputIterator, const Alloc&); template<class InputIterator, class Alloc> priority_queue(InputIterator, InputIterator, const Compare&, const Alloc&); template<class InputIterator, class Alloc> priority_queue(InputIterator, InputIterator, const Compare&, const Container&, const Alloc&); template<class InputIterator, class Alloc> priority_queue(InputIterator, InputIterator, const Compare&, Container&&, const Alloc&); [[nodiscard]] bool empty() const { return c.empty(); } size_type size() const { return c.size(); } const_reference top() const { return c.front(); } void push(const value_type& x); void push(value_type&& x); template<class... Args> void emplace(Args&&... args); void pop(); void swap(priority_queue& q) noexcept(is_nothrow_swappable_v<Container> && is_nothrow_swappable_v<Compare>) { using std::swap; swap(c, q.c); swap(comp, q.comp); } }; template<class Compare, class Container> priority_queue(Compare, Container) -> priority_queue<typename Container::value_type, Container, Compare>; template<class InputIterator, class Compare = less<iter-value-type<InputIterator>>, class Container = vector<iter-value-type<InputIterator>>> priority_queue(InputIterator, InputIterator, Compare = Compare(), Container = Container()) -> priority_queue<iter-value-type<InputIterator>, Container, Compare>; template<class Compare, class Container, class Allocator> priority_queue(Compare, Container, Allocator) -> priority_queue<typename Container::value_type, Container, Compare>; template<class InputIterator, class Allocator> priority_queue(InputIterator, InputIterator, Allocator) -> priority_queue<iter-value-type<InputIterator>, vector<iter-value-type<InputIterator>, Allocator>, less<iter-value-type<InputIterator>>>; template<class InputIterator, class Compare, class Allocator> priority_queue(InputIterator, InputIterator, Compare, Allocator) -> priority_queue<iter-value-type<InputIterator>, vector<iter-value-type<InputIterator>, Allocator>, Compare>; template<class InputIterator, class Compare, class Container, class Allocator> priority_queue(InputIterator, InputIterator, Compare, Container, Allocator) -> priority_queue<typename Container::value_type, Container, Compare>; // no equality is provided template<class T, class Container, class Compare, class Alloc> struct uses_allocator<priority_queue<T, Container, Compare>, Alloc> : uses_allocator<Container, Alloc>::type { }; }

22.6.5.2 Constructors [priqueue.cons]

🔗
priority_queue(const Compare& x, const Container& y); priority_queue(const Compare& x, Container&& y);
1
#
Preconditions: x defines a strict weak ordering ([alg.sorting]).
2
#
Effects: Initializes comp with x and c with y (copy constructing or move constructing as appropriate); calls make_­heap(c.begin(), c.end(), comp).
🔗
template<class InputIterator> priority_queue(InputIterator first, InputIterator last, const Compare& x = Compare());
3
#
Preconditions: x defines a strict weak ordering ([alg.sorting]).
4
#
Effects: Initializes c with first as the first argument and last as the second argument, and initializes comp with x; then calls make_­heap(c.begin(), c.end(), comp).
🔗
template<class InputIterator> priority_queue(InputIterator first, InputIterator last, const Compare& x, const Container& y); template<class InputIterator> priority_queue(InputIterator first, InputIterator last, const Compare& x, Container&& y);
5
#
Preconditions: x defines a strict weak ordering ([alg.sorting]).
6
#
Effects: Initializes comp with x and c with y (copy constructing or move constructing as appropriate); calls c.insert(c.end(), first, last); and finally calls make_­heap(c.begin(), c.end(), comp).

22.6.5.3 Constructors with allocators [priqueue.cons.alloc]

1
#
If uses_­allocator_­v<container_­type, Alloc> is false the constructors in this subclause shall not participate in overload resolution.
🔗
template<class Alloc> explicit priority_queue(const Alloc& a);
2
#
Effects: Initializes c with a and value-initializes comp.
🔗
template<class Alloc> priority_queue(const Compare& compare, const Alloc& a);
3
#
Effects: Initializes c with a and initializes comp with compare.
🔗
template<class Alloc> priority_queue(const Compare& compare, const Container& cont, const Alloc& a);
4
#
Effects: Initializes c with cont as the first argument and a as the second argument, and initializes comp with compare; calls make_­heap(c.begin(), c.end(), comp).
🔗
template<class Alloc> priority_queue(const Compare& compare, Container&& cont, const Alloc& a);
5
#
Effects: Initializes c with std​::​move(cont) as the first argument and a as the second argument, and initializes comp with compare; calls make_­heap(c.begin(), c.end(), comp).
🔗
template<class Alloc> priority_queue(const priority_queue& q, const Alloc& a);
6
#
Effects: Initializes c with q.c as the first argument and a as the second argument, and initializes comp with q.comp.
🔗
template<class Alloc> priority_queue(priority_queue&& q, const Alloc& a);
7
#
Effects: Initializes c with std​::​move(q.c) as the first argument and a as the second argument, and initializes comp with std​::​move(q.comp).
🔗
template<class InputIterator, class Alloc> priority_queue(InputIterator first, InputIterator last, const Alloc& a);
8
#
Effects: Initializes c with first as the first argument, last as the second argument, and a as the third argument, and value-initializes comp; calls make_­heap(c.begin(), c.end(), comp).
🔗
template<class InputIterator, class Alloc> priority_queue(InputIterator first, InputIterator last, const Compare& compare, const Alloc& a);
9
#
Effects: Initializes c with first as the first argument, last as the second argument, and a as the third argument, and initializes comp with compare; calls make_­heap(c.begin(), c.end(), comp).
🔗
template<class InputIterator, class Alloc> priority_queue(InputIterator first, InputIterator last, const Compare& compare, const Container& cont, const Alloc& a);
10
#
Effects: Initializes c with cont as the first argument and a as the second argument, and initializes comp with compare; calls c.insert(c.end(), first, last); and finally calls make_­heap(c.begin(), c.end(), comp).
🔗
template<class InputIterator, class Alloc> priority_queue(InputIterator first, InputIterator last, const Compare& compare, Container&& cont, const Alloc& a);
11
#
Effects: Initializes c with std​::​move(cont) as the first argument and a as the second argument, and initializes comp with compare; calls c.insert(c.end(), first, last); and finally calls make_­heap(c.begin(), c.end(), comp).

22.6.5.4 Members [priqueue.members]

🔗
void push(const value_type& x);
1
#
Effects: As if by: c.push_back(x); push_heap(c.begin(), c.end(), comp);
🔗
void push(value_type&& x);
2
#
Effects: As if by: c.push_back(std::move(x)); push_heap(c.begin(), c.end(), comp);
🔗
template<class... Args> void emplace(Args&&... args);
3
#
Effects: As if by: c.emplace_back(std::forward<Args>(args)...); push_heap(c.begin(), c.end(), comp);
🔗
void pop();
4
#
Effects: As if by: pop_heap(c.begin(), c.end(), comp); c.pop_back();

22.6.5.5 Specialized algorithms [priqueue.special]

🔗
template<class T, class Container, class Compare> void swap(priority_queue<T, Container, Compare>& x, priority_queue<T, Container, Compare>& y) noexcept(noexcept(x.swap(y)));
1
#
Constraints: is_­swappable_­v<Container> is true and is_­swappable_­v<Compare> is true.
2
#
Effects: As if by x.swap(y).

22.6.6 Class template stack [stack]

22.6.6.1 General [stack.general]

1
#
Any sequence container supporting operations back(), push_­back() and pop_­back() can be used to instantiate stack.
In particular, vector, list and deque can be used.

22.6.6.2 Definition [stack.defn]

namespace std { template<class T, class Container = deque<T>> class stack { public: using value_type = typename Container::value_type; using reference = typename Container::reference; using const_reference = typename Container::const_reference; using size_type = typename Container::size_type; using container_type = Container; protected: Container c; public: stack() : stack(Container()) {} explicit stack(const Container&); explicit stack(Container&&); template<class InputIterator> stack(InputIterator first, InputIterator last); template<class Alloc> explicit stack(const Alloc&); template<class Alloc> stack(const Container&, const Alloc&); template<class Alloc> stack(Container&&, const Alloc&); template<class Alloc> stack(const stack&, const Alloc&); template<class Alloc> stack(stack&&, const Alloc&); template<class InputIterator, class Alloc> stack(InputIterator first, InputIterator last, const Alloc&); [[nodiscard]] bool empty() const { return c.empty(); } size_type size() const { return c.size(); } reference top() { return c.back(); } const_reference top() const { return c.back(); } void push(const value_type& x) { c.push_back(x); } void push(value_type&& x) { c.push_back(std::move(x)); } template<class... Args> decltype(auto) emplace(Args&&... args) { return c.emplace_back(std::forward<Args>(args)...); } void pop() { c.pop_back(); } void swap(stack& s) noexcept(is_nothrow_swappable_v<Container>) { using std::swap; swap(c, s.c); } }; template<class Container> stack(Container) -> stack<typename Container::value_type, Container>; template<class InputIterator> stack(InputIterator, InputIterator) -> stack<iter-value-type<InputIterator>>; template<class Container, class Allocator> stack(Container, Allocator) -> stack<typename Container::value_type, Container>; template<class InputIterator, class Allocator> stack(InputIterator, InputIterator, Allocator) -> stack<iter-value-type<InputIterator>, deque<iter-value-type<InputIterator>, Allocator>>; template<class T, class Container, class Alloc> struct uses_allocator<stack<T, Container>, Alloc> : uses_allocator<Container, Alloc>::type { }; }

22.6.6.3 Constructors [stack.cons]

🔗
explicit stack(const Container& cont);
1
#
Effects: Initializes c with cont.
🔗
explicit stack(Container&& cont);
2
#
Effects: Initializes c with std​::​move(cont).
🔗
template<class InputIterator> stack(InputIterator first, InputIterator last);
3
#
Effects: Initializes c with first as the first argument and last as the second argument.

22.6.6.4 Constructors with allocators [stack.cons.alloc]

1
#
If uses_­allocator_­v<container_­type, Alloc> is false the constructors in this subclause shall not participate in overload resolution.
🔗
template<class Alloc> explicit stack(const Alloc& a);
2
#
Effects: Initializes c with a.
🔗
template<class Alloc> stack(const container_type& cont, const Alloc& a);
3
#
Effects: Initializes c with cont as the first argument and a as the second argument.
🔗
template<class Alloc> stack(container_type&& cont, const Alloc& a);
4
#
Effects: Initializes c with std​::​move(cont) as the first argument and a as the second argument.
🔗
template<class Alloc> stack(const stack& s, const Alloc& a);
5
#
Effects: Initializes c with s.c as the first argument and a as the second argument.
🔗
template<class Alloc> stack(stack&& s, const Alloc& a);
6
#
Effects: Initializes c with std​::​move(s.c) as the first argument and a as the second argument.
🔗
template<class InputIterator, class Alloc> stack(InputIterator first, InputIterator last, const Alloc& alloc);
7
#
Effects: Initializes c with first as the first argument, last as the second argument, and alloc as the third argument.

22.6.6.5 Operators [stack.ops]

🔗
template<class T, class Container> bool operator==(const stack<T, Container>& x, const stack<T, Container>& y);
1
#
Returns: x.c == y.c.
🔗
template<class T, class Container> bool operator!=(const stack<T, Container>& x, const stack<T, Container>& y);
2
#
Returns: x.c != y.c.
🔗
template<class T, class Container> bool operator< (const stack<T, Container>& x, const stack<T, Container>& y);
3
#
Returns: x.c < y.c.
🔗
template<class T, class Container> bool operator> (const stack<T, Container>& x, const stack<T, Container>& y);
4
#
Returns: x.c > y.c.
🔗
template<class T, class Container> bool operator<=(const stack<T, Container>& x, const stack<T, Container>& y);
5
#
Returns: x.c <= y.c.
🔗
template<class T, class Container> bool operator>=(const stack<T, Container>& x, const stack<T, Container>& y);
6
#
Returns: x.c >= y.c.
🔗
template<class T, three_­way_­comparable Container> compare_three_way_result_t<Container> operator<=>(const stack<T, Container>& x, const stack<T, Container>& y);
7
#
Returns: x.c <=> y.c.

22.6.6.6 Specialized algorithms [stack.special]

🔗
template<class T, class Container> void swap(stack<T, Container>& x, stack<T, Container>& y) noexcept(noexcept(x.swap(y)));
1
#
Constraints: is_­swappable_­v<Container> is true.
2
#
Effects: As if by x.swap(y).