`<queue>`

Include the STL standard header <queue> to define the template classes priority_queue and queue, and several supporting templates.

namespace std {
template<class Ty, class Container>
    class queue;
template<class Ty, class Container, class Pr>
    class priority_queue;

        // TEMPLATE FUNCTIONS
template<class Ty, class Container>
    bool operator==(const queue<Ty, Container>& left,
        const queue<Ty, Container>&);
template<class Ty, class Container>
    bool operator!=(const queue<Ty, Container>& left,
        const queue<Ty, Container>&);
template<class Ty, class Container>
    bool operator<(const queue<Ty, Container>& left,
        const queue<Ty, Container>&);
template<class Ty, class Container>
    bool operator>(const queue<Ty, Container>& left,
        const queue<Ty, Container>&);
template<class Ty, class Container>
    bool operator<=(const queue<Ty, Container>& left,
        const queue<Ty, Container>&);
template<class Ty, class Container>
    bool operator>=(const queue<Ty, Container>& left,
        const queue<Ty, Container>&);

template<class Ty, class Container>
    bool swap(queue<Ty, Container>& left,
        queue<Ty, Container>&)
            noexcept(noexcept(left.swap(right))); [added with C++11]
template<class Ty, class Container, class Pr>
    bool swap(priority_queue<Ty, Container, Pr>& left,
        priority_queue<Ty, Container, Pr>&)
            noexcept(noexcept(left.swap(right))); [added with C++11]

template<class Ty, class Container, class Alloc>
    struct uses_allocator<queue<Ty, Container>, alloc>; [added with C++11]
template<class Ty, class Container, class Pr, class Alloc>
    struct uses_allocator<priority_queue<Ty, Container, Pr>, alloc>; [added with C++11]
}  // namespace std

`operator!=`

template<class Ty, class Container>
    bool operator!=(const queue <Ty, Container>& left,
        const queue <Ty, Container>& right);

The template function returns !(left == right).

`operator==`

template<class Ty, class Container>
    bool operator==(const queue <Ty, Container>& left,
        const queue <Ty, Container>& right);

The template function overloads operator== to compare two objects of template class queue. The function returns left.c == right.c.

`operator<`

template<class Ty, class Container>
    bool operator<(const queue <Ty, Container>& left,
        const queue <Ty, Container>& right);

The template function overloads operator< to compare two objects of template class queue. The function returns left.c < right.c.

`operator<=`

template<class Ty, class Container>
    bool operator<=(const queue <Ty, Container>& left,
        const queue <Ty, Container>& right);

The template function returns !(right < left).

`operator>`

template<class Ty, class Container>
    bool operator>(const queue <Ty, Container>& left,
        const queue <Ty, Container>& right);

The template function returns right < left.

`operator>=`

template<class Ty, class Container>
    bool operator>=(const queue <Ty, Container>& left,
        const queue <Ty, Container>& right);

The template function returns !(left < right).

`priority_queue`

template<class Ty,
    class Container = vector<Ty>,
    class Pr = less<typename Container::value_type> >
    class priority_queue {
public:
    typedef Container container_type;
    typedef typename Container::value_type value_type;
    typedef typename Container::size_type size_type;
    typedef typename Container::reference reference;
    typedef typename Container::const_reference const_reference;

    priority_queue();
    explicit priority_queue(const Pr& pred);
    priority_queue(const Pr& pred,
        const container_type& cont);
    priority_queue(const priority_queue& right);
    template<class InIt>
        priority_queue(InIt first, InIt last);
    template<class InIt>
        priority_queue(InIt first, InIt last,
            const Pr& pred);
    template<class InIt>
        priority_queue(InIt first, InIt last,
            const Pr& pred, const container_type& cont);

    priority_queue(const Pr& pred,
        container_type&& cont); [added with C++11]
    priority_queue(priority_queue&& right)
        noexcept(is_nothrow_move_constructible<Container>::value
            && is_nothrow_move_constructible<Prr>::value); [added with C++11]
    template<class InIt>
        priority_queue(InIt first, InIt last,
            const Pr& pred, container_type&& cont); [added with C++11]

    template<class Allloc>
        explicit priority_queue(const Alloc& al); [added with C++11]
    template<class Allloc>
        priority_queue(const Pr& pred, const Alloc& al); [added with C++11]
    template<class Allloc>
        priority_queue(const Pr& pred,
            const container_type& cont, const Alloc& al); [added with C++11]
    template<class Allloc>
        priority_queue(const priority_queue& right,
            const Alloc& al); [added with C++11]
    template<class Allloc>
        priority_queue(const Pr& pred,
            container_type&& cont, const Alloc& al); [added with C++11]
    template<class Allloc>
        priority_queue(priority_queue&& right,
            const Alloc& al); [added with C++11]

    priority_queue operator=(priority_queue&& right)
        noexcept(is_nothrow_move_assignable<Container>::value
            && is_nothrow_move_assignable<Prr>::value); [added with C++11]
; [added with C++11]
    void swap(priority_queue& right)
        noexcept(noexcept(swap(c, right.c)
            && swap(comp, right.comp))); [added with C++11]

    bool empty() const;
    size_type size() const;
    const_reference top() const;
    void push(const value_type& val);
    void push(value_type&& val); [added with C++11]
    template<class... Ty>
        void emplace(Ty&&... val); [added with C++11]
    void pop();

protected:
    Container c;
    Pr comp;
    };

The template class describes an object that controls a varying-length sequence of elements. The object allocates and frees storage for the sequence it controls through a protected object named c, of class Container. The type Ty of elements in the controlled sequence must match value_type.

The sequence is ordered using a protected object named comp. After each insertion or removal of the top element (at position zero), for the iterators P0 and Pi designating elements at positions 0 and I, comp(*P0, *Pi) is false. (For the default template parameter less<typename Container::value_type> the top element of the sequence compares largest, or highest priority.)

An object of class Container must supply random-access iterators and several public members defined the same as for deque and vector (both of which are suitable candidates for class Container). The required members are:

    typedef Ty value_type;
    typedef T0 size_type;
    typedef T1 iterator;
    typedef T2 reference;
    typedef T3 const_reference;

    Container();
    template<class InIt>
        Container(InIt first, InIt last);

    template<class InIt>
        void insert(iterator where, InIt first, InIt last);
    iterator begin();
    iterator end();
    bool empty() const;
    size_type size() const;
    const_reference front() const;
    void push_back(const value_type& val);
    template<class... Ty>
        void emplace_back(const Ty&... val); [added with C++11]
    void pop_back();

Here, T0, T1, T2, and T3 are unspecified types that meet the stated requirements.

Moreover, beginning with C++11, it must be possible to swap two Container objects by calling the standard function std::swap.

`priority_queue::const_reference`

typedef typename Container::const_reference const_reference;

The type is a synonym for Container::const_reference.

`priority_queue::container_type`

typedef typename Container::container_type container_type;

The type is a synonym for the template parameter Container.

`priority_queue::empty`

bool empty() const;

The member function returns true for an empty controlled sequence.

`priority_queue::emplace`

template<class... Ty>
    void emplace(Ty&&... val); [added with C++11]

The member function executes:

c.emplace_back(forward<Ty>(val)...);
push_heap(c.begin(), c.end(), comp);

`priority_queue::operator=`

priority_queue> operator=(priority_queue&& right)
    noexcept(is_nothrow_move_assignable<Container>::value
        && is_nothrow_move_assignable<Prr>::value); [added with C++11]

The operator moves right, as an rvalue reference to *this.

`priority_queue::pop`

void pop();

The member function removes the first element of the controlled sequence, which must be non-empty, then reorders it.

`priority_queue::priority_queue`

priority_queue();
explicit priority_queue(const Pr& pred);
priority_queue(const Pr& pred,
    const container_type& cont);
priority_queue(const priority_queue& right);
template<class InIt>
    priority_queue(InIt first, InIt last);
template<class InIt>
    priority_queue(InIt first, InIt last,
        const Pr& pred);
template<class InIt>
    priority_queue(InIt first, InIt last,
        const Pr& pred, const container_type& cont);

priority_queue(const Pr& pred,
    container_type&& cont)
        noexcept(is_nothrow_move_constructible<Container>::value
            && is_nothrow_move_constructible<Prr>::value); [added with C++11]
priority_queue(priority_queue&& right); [added with C++11]
template<class InIt>
    priority_queue(InIt first, InIt last,
        const Pr& pred, container_type&& cont); [added with C++11]

template<class Allloc>
    explicit priority_queue(const Alloc& al); [added with C++11]
template<class Allloc>
    priority_queue(const Pr& pred, const Alloc& al); [added with C++11]
template<class Allloc>
    priority_queue(const Pr& pred,
        const container_type& cont, const Alloc& al); [added with C++11]
template<class Allloc>
    priority_queue(const priority_queue& right,
        const Alloc& al); [added with C++11]
template<class Allloc>
    priority_queue(const Pr& pred,
        container_type&& cont, const Alloc& al); [added with C++11]
template<class Allloc>
    priority_queue(priority_queue&& right,
        const Alloc& al); [added with C++11]

All constructors with an argument cont initialize the stored object with c(cont). The remaining constructors initialize the stored object with c(), to specify an empty initial controlled sequence. The constructors with arguments first and last then call c.insert(c.end(), first, last).

The three constructors:

priority_queue(const Pr& pred,
    container_type&& cont)
        noexcept(is_nothrow_move_constructible<Container>::value
            && is_nothrow_move_constructible<Prr>::value); [added with C++11]
priority_queue(priority_queue&& right); [added with C++11]
template<class InIt>
    priority_queue(InIt first, InIt last,
        const Pr& pred, container_type&& cont); [added with C++11]

behave the same as earlier ones, but with an rvalue reference.

The remaining group behave the same as earlier constructors, but with an added allocator argument. Unless uses_allocator<Container, Alloc> holds true, these constructors do not participate in overload resolution.

All constructors also store a function object in comp. The function object comp is the argument pred, if present. For the copy constructor, it is right.comp. Otherwise, it is Pr().

A non-empty initial controlled sequence is then ordered by calling make_heap(c.begin(), c.end(), comp).

`priority_queue::push`

void push(const Ty& val);
void push(value_type&& val); [added with C++11]

The first member function inserts an element with value val at the end of the controlled sequence, then reorders it.

The second member functions is the same as the first, but with an rvalue reference.

`priority_queue::reference`

typedef typename Container::reference reference;

The type is a synonym for Container::reference.

`priority_queue::size`

size_type size() const;

The member function returns the length of the controlled sequence.

`priority_queue::size_type`

typedef typename Container::size_type size_type;

The type is a synonym for Container::size_type.

`priority_queue::swap`

void swap(priority_queue& right)
    noexcept(noexcept(swap(c, right.c)
        && swap(comp, right.comp))); [added with C++11]

The template function swaps right with *this, using std::swap.

`priority_queue::top`

const_reference top() const;

The member function returns a reference to the first (highest priority) element of the controlled sequence, which must be non-empty.

`priority_queue::value_type`

typedef typename Container::value_type value_type;

The type is a synonym for Container::value_type.

`queue`

template<class Ty,
    class Container = deque<Ty> >
    class queue {
public:
    typedef Container container_type;
    typedef typename Container::value_type value_type;
    typedef typename Container::size_type size_type;
    typedef typename Container::reference reference;
    typedef typename Container::const_reference const_reference;

    queue();
    queue(const queue& right);
    explicit queue(const container_type& cont);
    queue(queue&& right)
        noexcept(is_nothrow_move_constructible<Container>::value); [added with C++11]
    explicit queue(container_type&& cont); [added with C++11]

    explicit queue(const Alloc& al); [added with C++11]
    queue(const queue& right, const Alloc& al); [added with C++11]
    queue(const container_type& cont, const Alloc& al); [added with C++11]
    queue(queue&& right, const Alloc& al); [added with C++11]
    queue(container_type&& cont, const Alloc& al); [added with C++11]

    queue operator=(queue&& right)
        noexcept(is_nothrow_move_assignable<Container>::value); [added with C++11]
    void swap(queue& right)
        noexcept(noexcept(swap(c, right.c))); [added with C++11]

    bool empty() const;
    size_type size() const;

    reference back();
    const_reference back() const;
    reference front();
    const_reference front() const;

    void push(const value_type& val);
    void push(value_type&& val); [added with C++11]
    template<class... Ty>
        void emplace(Ty&&... val); [added with C++11]
    void pop();

protected:
    Container c;
    };

An object of class Container must supply several public members defined the same as for deque and list (both of which are suitable candidates for class Container). The required members are:

    typedef Ty value_type;
    typedef T0 size_type;
    typedef T1 reference;
    typedef T2 const_reference;

    Container();
    bool empty() const;
    size_type size() const;
    reference front();
    const_reference front() const;
    reference back();
    const_reference back() const;
    void push_back(const value_type& val);
    template<class... Ty>
        void emplace_back(const Ty&... val); [added with C++11]
    void pop_front();

    bool operator==(const Container& cont) const;
    bool operator!=(const Container& cont) const;
    bool operator<(const Container& cont) const;
    bool operator>(const Container& cont) const;
    bool operator<=(const Container& cont) const;
    bool operator>=(const Container& cont) const;

Here, T0, T1, and T2 are unspecified types that meet the stated requirements.

Moreover, beginning with C++11, it must be possible to swap two Container objects by calling the standard function std::swap.

`queue::back`

reference back();
const_reference back() const;

The member function returns a reference to the last element of the controlled sequence, which must be non-empty.

`queue::const_reference`

typedef typename Container::const_reference const_reference;

The type is a synonym for Container::const_reference.

`queue::container_type`

typedef Container container_type;

The type is a synonym for the template parameter Container.

`queue::emplace`

template<class... Ty>
    void emplace(Ty&&... val); [added with C++11]

The member function executes:

c.emplace_back(forward<Ty>(val)...);

`queue::empty`

bool empty() const;

The member function returns true for an empty controlled sequence.

`queue::front`

reference front();
const_reference front() const;

The member function returns a reference to the first element of the controlled sequence, which must be non-empty.

`queue::operator=`

queue> operator=(queue&& right)
    noexcept(is_nothrow_move_assignable<Container>::value); [added with C++11]

The operator moves right to *this.

`queue::pop`

void pop();

The member function removes the first element of the controlled sequence, which must be non-empty.

`queue::push`

void push(const Ty& val);
void push(value_type&& val); [added with C++11]

The first member function inserts an element with value val at the end of the controlled sequence.

The second member functions is the same as the first, but with an rvalue reference.

`queue::queue`

queue();
queue(const queue& right);
explicit queue(const container_type& cont);
queue(queue&& right); [added with C++11]
explicit queue(container_type&& cont)
    noexcept(is_nothrow_move_constructible<Container>::value); [added with C++11]

explicit queue(const Alloc& al); [added with C++11]
queue(const queue& right, const Alloc& al); [added with C++11]
queue(const container_type& cont, const Alloc& al); [added with C++11]
queue(queue&& right, const Alloc& al); [added with C++11]
queue(container_type&& cont, const Alloc& al); [added with C++11]

The first constructor initializes the stored object with c(), to specify an empty initial controlled sequence. The second constructor initializes the stored object with right.c, to specify an initial controlled sequence that is a copy of the sequence controlled by right.c. The third constructor initializes the stored object with c(cont), to specify an initial controlled sequence that is a copy of the sequence controlled by cont.

The fourth constructor is a move constructor, and the fifth is the same as the third but with an rvalue reference.

`queue::reference`

typedef typename Container::reference reference;

The type is a synonym for Container::reference.

`queue::size`

size_type size() const;

The member function returns the length of the controlled sequence.

`queue::size_type`

typedef typename Container::size_type size_type;

The type is a synonym for Container::size_type.

`queue::swap`

void swap(queue&& right)
    noexcept(noexcept(swap(c, right.c))); [added with C++11]

The template function swaps right with *this, using std::swap.

`queue::value_type`

typedef typename Container::value_type value_type;

The type is a synonym for Container::value_type.

`swap`

template<class Ty, class Container>
    bool swap(queue<Ty, Container>& left,
        queue<Ty, Container>&)
            noexcept(noexcept(left.swap(right))); [added with C++11]
template<class Ty, class Container, class Pr>
    bool swap(priority_queue<Ty, Container, Pr>& left,
        priority_queue<Ty, Container, Pr>&)
            noexcept(noexcept(left.swap(right))); [added with C++11]

The template function executes left.swap(right).

`uses_allocator`

template<class Ty, class Container, class Alloc>
    struct uses_allocator<queue<Ty, Container>, alloc>; [added with C++11]
template<class Ty, class Container, class Pr, class Alloc>
    struct uses_allocator<priority_queue<Ty, Container, Pr>, alloc>; [added with C++11]

The specializations hold true only if uses_allocator<Container, Alloc> holds true.

See also the Table of Contents and the Index.