|
Common Methods of the Priority Queues
Synopsis
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
|