edu.stanford.nlp.util

Interface PriorityQueue<E>

All Superinterfaces:

java.util.Collection<E>, java.lang.Iterable<E>, java.util.Set<E>

All Known Implementing Classes:

BinaryHeapPriorityQueue, FixedPrioritiesPriorityQueue

public interface PriorityQueue<E>
extends java.util.Set<E>

A Set that also represents an ordering of its elements, and responds quickly to add(), changePriority(), removeFirst(), and getFirst() method calls.

There are several important differences between this interface and the JDK PriorityQueue:

1. This interface uses explicitly-assigned double values as priorities for queue elements, while java.util.PriorityQueue uses either the elements' natural order (see Comparable) or a Comparator.
2. In this interface, larger doubles represent higher priorities; in java.util.PriorityQueue, lesser elements (with respect to the specified ordering) have higher priorities.
3. This interface enables you to change the priority of an element after it has entered the queue. With java.util.PriorityQueue, that's not possible.
4. However, there is a price to pay for this flexibility. The primary implementation of this interface, BinaryHeapPriorityQueue, is roughly 2x slower than java.util.PriorityQueue in informal benchmark testing.
5. So, there's another implementation of this interface, FixedPrioritiesPriorityQueue, which trades flexibility for speed: while it is up to 2x faster than BinaryHeapPriorityQueue and nearly as fast as PriorityQueue, it does not support removing or changing the priority of an element.

On the other hand, this interface and PriorityQueue also have some characteristics in common:

1. Both make no guarantee about the order in which elements with equal priority are returned from the queue. This does not mean that equal elements are returned in random order. (In fact they are returned in an order which depends on the order of insertion — but the implementations reserve the right to return them in any order whatsoever.)

Author:

Teg Grenager (grenager@cs.stanford.edu), Bill MacCartney

Method Summary

Methods

Modifier and Type	Method and Description
boolean	add(E key, double priority) Convenience method for if you want to pretend relaxPriority doesn't exist, or if you really want add's return conditions.
boolean	changePriority(E key, double priority) Changes a priority, either up or down, adding the key it if it wasn't there already.
E	getFirst() Finds the object with the highest priority and returns it, without modifying the queue.
double	getPriority() Gets the priority of the highest-priority element of the queue (without modifying the queue).
double	getPriority(E key) Get the priority of a key.
boolean	relaxPriority(E key, double priority) Increases the priority of the E key to the new priority if the old priority was lower than the new priority.
E	removeFirst() Finds the object with the highest priority, removes it, and returns it.
java.util.List<E>	toSortedList()
java.lang.String	toString(int maxKeysToPrint) Returns a representation of the queue in decreasing priority order, displaying at most maxKeysToPrint elements.

Methods inherited from interface java.util.Set

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray

Method Detail

removeFirst

E removeFirst()

Finds the object with the highest priority, removes it, and returns it.

Returns:

the object with highest priority

getFirst

E getFirst()

Finds the object with the highest priority and returns it, without modifying the queue.

Returns:

the object with minimum key

getPriority

double getPriority()

Gets the priority of the highest-priority element of the queue (without modifying the queue).

Returns:

The priority of the highest-priority element of the queue.

getPriority

double getPriority(E key)

Get the priority of a key.

Parameters:

key - The object to assess

Returns:

A key's priority. If the key is not in the queue, Double.NEGATIVE_INFINITY is returned.

add

boolean add(E key,
          double priority)

Convenience method for if you want to pretend relaxPriority doesn't exist, or if you really want add's return conditions.

Returns:

true if this set did not already contain the specified element.

changePriority

boolean changePriority(E key,
                     double priority)

Changes a priority, either up or down, adding the key it if it wasn't there already.

Parameters:

key - an E value

Returns:

whether the priority actually changed.

relaxPriority

boolean relaxPriority(E key,
                    double priority)

Increases the priority of the E key to the new priority if the old priority was lower than the new priority. Otherwise, does nothing.

toSortedList

java.util.List<E> toSortedList()

toString

java.lang.String toString(int maxKeysToPrint)

Returns a representation of the queue in decreasing priority order, displaying at most maxKeysToPrint elements.

Parameters:

maxKeysToPrint - The maximum number of keys to print. Less are printed if there are less than this number of items in the PriorityQueue. If this number is non-positive, then all elements in the PriorityQueue are printed.

Returns:

A String representation of the high priority items in the queue.