priority_queue Interface

# `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: `binary_heap_tag` `binomial_heap_tag` `rc_binomial_heap_tag` `pairing_heap_tag` `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.