# Common Methods of the Priority Queues

# Synopsis

    template <typename Heap>
    void example()
    {
      typedef typename Heap::value_type      value_type;
      typedef typename Heap::size_type       size_type;
      typedef typename Heap::pointer         pointer;
      typedef typename Heap::const_iterator  const_iterator;
      typedef typename Heap::const_reference const_reference;
      typedef typename Heap::compare_type    compare_type;

      Heap heap; // default constructor

      heap.push(value_type());
      heap.top();
      heap.pop();
      heap.size();
      heap.empty();

      const_iterator beg = heap.begin();
      const_iterator end = heap.end();

      pointer ptr = heap.push(value_type());
      heap.change_top(value_type());
      heap.change(ptr, value_type());
      heap.decrease(ptr, value_type());
      heap.increase(ptr, value_type());
      heap.remove(ptr);
    }

# Description

This page describes the common members of the various priority queue classes: The common members have the same semantics and are thus only described just once. However, not all of the members described here are supported for all priority classes. See the respective manual page for the members supported. Also the manual pages for the individual priority queues document briefly how the class implemented.

# Typedefs

A few types are defined for the priority classes to support their generic manipulation.

### `Heap::value_type`

The typedef `value_type` identifies the type of the objects stored in the priority queue. This type is used as argument for the `push()` member to insert a new element into the heap. The member `top()` returns a reference to a constant object of this type.

### `Heap::size_type`

The typedef `size_type` identifies the type used to maintain the number of the elements in the priority queue. The member `size()` returns an object of this type.

### `Heap::pointer`

The type `pointer` is used to represent handles to objects inserted into a priority queue. These handles are used for efficient lookup of the object when the object's priority is changed using one of the functions `change()`, `increase()`, or `decrease()`. Whether this type really is a pointer like the name suggests of some other handle type is not defined. Objects of this type should be handled as opaque objects.

### `Heap::const_reference`

The method `top()` returns this type to access the largest element in the priority queue.

### `Heap::const_iterator`

Objects of the type `const_iterator` are used to iterate over all objects currently stored in a priority queue. The members `begin()` and `end()` return objects of this type.

### `Heap::compare_type`

`Heap::compare_type` is the type of the comparator object used to compare elements of the priority queue. This type is not defined by all priority classes because some priority classes can't be parameterized with a compare type. Where this type is present, it defaults to `std::less<value_type>`.

# Member Functions

### `Heap::Heap()`

Effect
  The default constructor creates an empty object. In some cases, namely when the comparator class does not have a default constructor, the default constructor is not available. In this case you have to pass a comparator to the constructor of the priority queue (i.e. the comparator has to be copy constructible).

### `Heap::push(val)`

Effect
  The function `push()` inserts a copy of `val` into the corresponding priority queue. If the priority queue supports changing the priority of arbitrary elements, a `pointer` to the newly inserted element is inserted.
Return
  A `pointer` is returned if arbitrary priority changes are supported by the priority class. Otherwise, `void` is returned.
Postcondition
  `size()` is increased by one and `top()` returns a reference to the new object if it is larger than all elements stored in the priority. Whether the `top()` returns a reference to the new object or some other object, if the new object compares equal to the largest element previously stored in the priority queue is not specified.

### `Heap::top()`

Effect
  This member functions provides efficient access to the largest element in the priority queue. Some implementations determine the minimum element when `top()` is called although this member function is declared to be `const`: This is a typical case of logical constness vs. `bitwise constness`. Although the observable state of the object does not change (the logic view of the object does not change), the data structure might be update on this request internally, ie. the actual representation changes.
Return
  A reference to the largest object is returned. Note, that the referenced object is constant.
Precondition
  There has to be at least one element in the priority queue, i.e. `empty()` has to return `false`.

### `Heap::pop()`

Effect
  The function `pop()` removes the largest element from the priority queue. If there are multiple copies of the largest element stored in the priority queue, only one of those elements is removed.
Precondition
  There has to be at least one element in the priority queue, i.e. `empty()` has to return `false`.
Postcondition
  The largest element is removed from the priority queue and correspondingly the value returned from `size()` is reduced by one.

### `Heap::empty()`

Return
  If `size() > 0` then `false` is returned, otherwise `true` is returned.

### `Heap::size()`

Return
  The number of elements currently stored in the priority queue is returned.

### `Heap::begin()`

Effect
  The member function `begin()` returns an iterator defining the beginning of the sequence representing all elements stored in the priority queue. The end of the sequence is returned by `end()`.

  The returned iterator in general only conforms to the input iterator requirements. Some classes support more specific iterators but probably the application should no rely on other requirements to allow easy replacement of the selected priority queue.

  The order in which the elements are accessed is in general unspecified. However, for some classes there is a specific order. If this is the case, the manual page of the respective priority queue class will describe this order.

Return
  The start iterator for the sequence of all elements in the priority queue is returned.

### `Heap::end()`

Effect
  The member function `end()` returns an iterator defining the end of the sequence representing all elements stored in the priority queue. The begin of the sequence is returned by `begin()`. See the documention of this function for more details.
Return
  The end iterator for the sequence of all elements in the priority queue is returned.

### `Heap::change_top(val)`

Effect
  The member function `change_top()` is used to change the priority of the currently largest element to `val`. This is basically identical to a `pop()` followed by to `push(val)`. However, `change_top()` may be significantly more efficient for some priority queue classes: For example, when changing the top of a d-heap, the corresponding element only has to moved down as far as necessary. Removal and insertion would make a complete pass from root to leaf (for removal) and leaf to root (for insertion).
Precondition
  There has to be at least one element in the priority queue, i.e. `empty()` has to return `false`.
Postcondition
  The priority of the top element is adjusted to `val` and correspondingly the data structure is updated to make the new largest element the new top. Of course, if the changed element remained the largest, it may stay the top.
Note
  This function is a member template to make it possible to change only the priority in composite elements: To do so, the assignment operator (`operator=()`) can be overloaded to take a type which is then passed to this function changing selectively the priority.

### `Heap::change(ptr, val)`

Effect
  The priority of the element identified by `ptr` is changed to `val`.
Precondition
  The object identified by `ptr` is indeed an element of the priority queue on which the `change()` method is called. In particular, this means that there is at least one element in the priority queue.
Note
  This function is a member template to make it possible to change only the priority in composite elements: To do so, the assignment operator (`operator=()`) can be overloaded to take a type which is then passed to this function changing selectively the priority.

### `Heap::decrease(ptr, val)`

Effect
  The priority of the element identified by `ptr` is changed to `val`. This function assumes that `val` is smaller than the current priority of the element: This is not checked at all. This method is useful if it is known that the priority is guaranteed to be smaller than the current priority.
Precondition
  The object identified by `ptr` is indeed an element of the priority queue on which the `decrease()` method is called. In particular, this means that there is at least one element in the priority queue.
Note
  This function is a member template to make it possible to change only the priority in composite elements: To do so, the assignment operator (`operator=()`) can be overloaded to take a type which is then passed to this function changing selectively the priority.

### `Heap::increase(ptr, val)`

Effect
  The priority of the element identified by `ptr` is changed to `val`. This function assumes that `val` is greater than the current priority of the element: This is not checked at all. This method is useful if it is known that the priority is guaranteed to be greater than the current priority.
Precondition
  The object identified by `ptr` is indeed an element of the priority queue on which the `decrease()` method is called. In particular, this means that there is at least one element in the priority queue.
Note
  This function is a member template to make it possible to change only the priority in composite elements: To do so, the assignment operator (`operator=()`) can be overloaded to take a type which is then passed to this function changing selectively the priority.

### `Heap::remove(ptr)`

Effect
  This method removes the element identified by `ptr` from the priority queue.
Precondition
  The object identified by `ptr` is indeed an element of the priority queue on which the `remove()` method is called. In particular, this means that there is at least one element in the priority queue.

# See Also

d_heap(3), f_heap(3), l_heap(3), p_heap(3), p_queue(3), queue(3), r_heap(3), stack(3)

Copyright © 1999 Dietmar Kühl (dietmar.kuehl@claas-solutions.de)
Claas Solutions GmbH