edu.stanford.nlp.util.PriorityQueue Maven / Gradle / Ivy

Go to download
package edu.stanford.nlp.util;

import java.util.List;
import java.util.Set;

/**
 * A Set that also represents an ordering of its elements, and responds
 * quickly to {@code add()}, {@code changePriority()},
 * {@code removeFirst()}, and {@code getFirst()} method calls. 
 *
 * There are several important differences between this interface and
 * the JDK {@link java.util.PriorityQueue}: 

 * 

 *  This interface uses explicitly-assigned double values
 * as priorities for queue elements, while
 * java.util.PriorityQueue uses either the elements'
 * natural order (see {@link java.lang.Comparable}) or a {@link
 * java.util.Comparator}.
 *
 *  In this interface, larger doubles represent higher
 * priorities; in java.util.PriorityQueue, lesser
 * elements (with respect to the specified ordering) have higher
 * priorities.
 *
 *  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.
 *
 *  However, there is a price to pay for this flexibility.  The primary
 * implementation of this interface, {@link
 * edu.stanford.nlp.util.BinaryHeapPriorityQueue}, is roughly 2x slower
 * than java.util.PriorityQueue in informal benchmark
 * testing.
 *
 *  So, there's another implementation of this interface,
 * FixedPrioritiesPriorityQueue, which trades flexibility for speed: while
 * it is up to 2x faster than {@link BinaryHeapPriorityQueue} and nearly as
 * fast as {@link java.util.PriorityQueue}, it does not support removing or
 * changing the priority of an element.
 * 
 * 
 * On the other hand, this interface and {@link java.util.PriorityQueue}
 * also have some characteristics in common: 

 * 

 *  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 ([email protected])
 * @author Bill MacCartney
 */
public interface PriorityQueue extends Set {

  /**
   * Finds the object with the highest priority, removes it,
   * and returns it.
   *
   * @return the object with highest priority
   */
  public E removeFirst();

  /**
   * Finds the object with the highest priority and returns it, without
   * modifying the queue.
   *
   * @return the object with minimum key
   */
  public E getFirst();

  /**
   * Gets the priority of the highest-priority element of the queue
   * (without modifying the queue).
   *
   * @return The priority of the highest-priority element of the queue.
   */
  public double getPriority();

  /**
   * Get the priority of a key.
   *
   * @param key The object to assess
   * @return A key's priority. If the key is not in the queue,
   *         Double.NEGATIVE_INFINITY is returned.
   */
  public double getPriority(E key);

  /**
   * Convenience method for if you want to pretend relaxPriority doesn't exist,
   * or if you really want to use the return conditions of add().
   * 
   * Warning: The semantics of this method currently varies between implementations.
   * In some implementations, nothing will be changed if the key is already in the
   * priority queue. In others, the element will be added a second time with the
   * new priority. We maybe should at least change things so that the priority
   * will be change to the priority given if the element is in the queue with
   * a lower priority, but that wasn't the historical behavior, and it seemed like
   * we'd need to do a lot of archeology before changing the behavior.
   *
   * @return true if this set did not already contain the specified
   *         element.
   */
  public boolean add(E key, double priority);


  /**
   * Changes a priority, either up or down, adding the key it if it wasn't there already.
   *
   * @param key an E value
   * @return whether the priority actually changed.
   */
  public boolean changePriority(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.
   *
   */
  public boolean relaxPriority(E key, double priority);

  public List toSortedList();

  /**
   * Returns a representation of the queue in decreasing priority order,
   * displaying at most maxKeysToPrint elements.
   *
   * @param 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.
   * @return A String representation of the high priority items in the queue.
   */
  public String toString(int maxKeysToPrint);

}