# `priority_queue` Interface

Basic priority queue.

Defined in: `priority_queue.hpp`

## Template Parameters

Parameter | Description | Default Value

    typename Value_Type

Value type.

-

    class Cmp_Fn

Comparison functor.

    std::less<Value_Type>

    class Tag

Data-structure tag.

`pairing_heap_tag`

    class Allocator

Allocator type.

    std::allocator<char>

## Public Types and Constants

### General Container Definitions

Type | Definition | Description

    size_type

    typename Allocator::size_type

Size type.

    difference_type

    typename Allocator::difference_type

Difference type.

### Categories

Type | Definition | Description

    container_category

    Tag

The underlying mapped-structure tag of the container.

This is one of:

1. `binary_heap_tag`
2. `binomial_heap_tag`
3. `rc_binomial_heap_tag`
4. `pairing_heap_tag`
5. `thin_heap_tag`

### Policy Definitions

Type | Definition | Description

    cmp_fn

    Cmp_Fn

Comparison functor type.

    allocator

    Allocator

`Allocator` type.

### Value-Type Definitions

Type | Definition | Description

    value_type

    Value_Type

Value type.

    reference

    typename allocator::template rebind<
        value_type>::other::reference

Value reference type.

    const_reference

    typename allocator::template rebind<
        value_type>::other::const_reference

Const value `reference` type.

    pointer

    typename allocator::template rebind<
        value_type>::other::pointer

Value pointer type.

    const_pointer

    typename allocator::template rebind<
        value_type>::other::const_pointer

Const Value `pointer` type.

### Iterator Definitions

Type | Definition | Description

    const_point_iterator

    Const point-type iterator.

Const point-type iterator.

    point_iterator

    Point-type iterator.

Point-type iterator.

    const_iterator

    Const range-type iterator.

Const range-type iterator.

    iterator

    Range-type iterator.

Range-type iterator.

## Public Methods

### Constructors, Destructor, and Related

Method | Description

      priority_queue
      ()

Default constructor.

      priority_queue
      (const cmp_fn &r_cmp_fn)

Constructor taking some policy objects. `r_cmp_fn` will be copied by the `Cmp_Fn` object of the container object.

    template<
        class It>
      priority_queue
      (It first_it,
        It last_it)

Constructor taking iterators to a range of `value_type`s. The `value_type`s between `first_it` and `last_it` will be inserted into the container object.

    template<
        class It>
      priority_queue
      (It first_it,
        It last_it,
        const cmp_fn &r_cmp_fn)

Constructor taking iterators to a range of `value_type`s and some policy objects The `value_type`s between `first_it` and `last_it` will be inserted into the container object. `r_cmp_fn` will be copied by the `cmp_fn` object of the container object.

      priority_queue
      (const priority_queue &other)

Copy constructor.

    virtual
      ~priority_queue
      ()

Destructor.

    priority_queue &
      operator=
      (const priority_queue &other)

Assignment operator.

    void
      swap
      (priority_queue &other)

Swaps content.

### Information Methods

Method | Description

    inline size_type
      size
      () const

Returns the number of distinct `value_type` objects the container object is storing.

    inline size_type
      max_size
      () const

Returns an upper bound on the number of distinct `value_type` objects this container can store.

    inline bool
      empty
      () const

Returns whether the container object is not storing any `value_type` objects.

### Insert Methods

Method | Description

    inline point_iterator
      push
      (const_reference r_val)

Inserts a `value_type` object. returns a `point_iterator` object associated with the new pushed `r_val`.

### Find Methods

Method | Description

    inline const_reference
      top
      () const

Returns the `const_reference` of the largest `value_type` in the container object, i.e., a `value_type` v_max for which any other `value_type` v in the container object will satisfy !`cmp_fn`()(v_max, v).

### Modify Methods

Method | Description

    inline void
      modify
      (point_iterator it,
        const_reference r_new_val)

Modifies the `value_type` associated with the `point_iterator` `it` into `r_new_val`.

To use this method, `value_type` must be assignable.

### Erase Methods

Method | Description

    inline void
      pop
      ()

Pops the largest `value_type`.

If the container object is empty, results are undefined.

    inline void
      erase
      (point_iterator it)

Erases the `value_type` associated with the `point_iterator` `it`.

    template<
      class Pred>
    inline size_type
      erase_if
      (Pred prd)

Erases any `value_type` satisfying the predicate `prd`; returns the number of `value_type`s erased.

    void
      clear
      ()

Clears the container object.

### Split and join Methods

Method | Description

    void
      join
      (priority_queue &other)

Joins two container objects. When this function returns, `other` will be empty.

When calling this method, `other`'s policies must be equivalent to this object's policies.

    template<
      class Pred>
    inline void
      split
      (Pred prd,
        priority_queue &other)

Splits into two container objects. When this function returns, `other` will be contain only values v for which `prd`(v) is `true`.

When calling this method, `other`'s policies must be equivalent to this object's policies.

### Iteration Methods

Method | Description

    inline iterator
      begin
      ()

Returns an `iterator` corresponding to the first `value_type` in the container.

    inline const_iterator
      begin
      () const

Returns a `const_iterator` corresponding to the first `value_type` in the container.

    inline iterator
      end
      ()

Returns an `iterator` corresponding to the just-after-last `value_type` in the container.

    inline const_iterator
      end
      () const

Returns a `const_iterator` corresponding to the just-after-last `value_type` in the container.