001: package it.unimi.dsi.fastutil;
002:
003: /*
004: * fastutil: Fast & compact type-specific collections for Java
005: *
006: * Copyright (C) 2003-2008 Paolo Boldi and Sebastiano Vigna
007: *
008: * This library is free software; you can redistribute it and/or
009: * modify it under the terms of the GNU Lesser General Public
010: * License as published by the Free Software Foundation; either
011: * version 2.1 of the License, or (at your option) any later version.
012: *
013: * This library is distributed in the hope that it will be useful,
014: * but WITHOUT ANY WARRANTY; without even the implied warranty of
015: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
016: * Lesser General Public License for more details.
017: *
018: * You should have received a copy of the GNU Lesser General Public
019: * License along with this library; if not, write to the Free Software
020: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
021: *
022: */
023:
024: import java.util.Comparator;
025: import java.util.NoSuchElementException;
026:
027: /** A priority queue.
028: *
029: * <P>A priority queue provides a way to {@linkplain #enqueue(Object) enqueue}
030: * elements, and to {@linkplain #dequeue() dequeue} them in some specified
031: * order. Elements that are <em>smaller</em> in the specified order are
032: * dequeued first. It is also possible to get the {@linkplain #first() first
033: * element}, that is, the element that would be dequeued next.
034: *
035: * <P>Additionally, the queue may provide a method to peek at
036: * element that would be dequeued {@linkplain #last() last}.
037: *
038: * <P>The relative order of the elements enqueued should not change during
039: * queue operations. Nonetheless, some implementations may give the caller a
040: * way to notify the queue that the {@linkplain #changed() first element has
041: * changed its relative position in the order}.
042: */
043:
044: public interface PriorityQueue<K> {
045:
046: /** Enqueues a new element.
047: *
048: * @param x the element to enqueue..
049: */
050:
051: void enqueue(K x);
052:
053: /** Dequeues the {@link #first()} element from the queue.
054: *
055: * @return the dequeued element.
056: * @throws NoSuchElementException if the queue is empty.
057: */
058:
059: K dequeue();
060:
061: /** Checks whether the queue is empty.
062: *
063: * @return true if the queue is empty.
064: */
065:
066: boolean isEmpty();
067:
068: /** Returns the number of elements in this queue.
069: *
070: * @return the number of elements in this queue.
071: */
072:
073: int size();
074:
075: /** Removes all elements from this queue.
076: */
077:
078: void clear();
079:
080: /** Returns the first element of the queue.
081: *
082: * @return the first element.
083: * @throws NoSuchElementException if the queue is empty.
084: */
085:
086: K first();
087:
088: /** Returns the last element of the queue, that is, the element the would be dequeued last (optional operation).
089: *
090: * @return the last element.
091: * @throws NoSuchElementException if the queue is empty.
092: */
093:
094: K last();
095:
096: /** Notifies the queue that the {@linkplain #first() first element} has changed (optional operation).
097: */
098:
099: void changed();
100:
101: /** Returns the comparator associated with this queue, or <code>null</code> if it uses its elements' natural ordering.
102: *
103: * @return the comparator associated with this sorted set, or <code>null</code> if it uses its elements' natural ordering.
104: */
105: Comparator<? super K> comparator();
106: }
|