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