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

Show more of this group Show more artifacts with this name
Show all versions of stanford-corenlp Show documentation

Stanford CoreNLP provides a set of natural language analysis tools which can take raw English language text input and give the base forms of words, their parts of speech, whether they are names of companies, people, etc., normalize dates, times, and numeric quantities, mark up the structure of sentences in terms of phrases and word dependencies, and indicate which noun phrases refer to the same entities. It provides the foundational building blocks for higher level text understanding applications.

There is a newer version: 4.5.7

Show newest version

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);

}