--- jsr166/src/main/java/util/PriorityQueue.java 2003/05/14 21:30:45 1.1 +++ jsr166/src/main/java/util/PriorityQueue.java 2003/08/04 16:14:48 1.19 @@ -1,64 +1,453 @@ -package java.util; - -import java.util.*; + package java.util; /** - * An unbounded (resizable) priority queue based on a priority - * heap.The take operation returns the least element with respect to - * the given ordering. (If more than one element is tied for least - * value, one of them is arbitrarily chosen to be returned -- no - * guarantees are made for ordering across ties.) Ordering follows the - * java.util.Collection conventions: Either the elements must be - * Comparable, or a Comparator must be supplied. Comparison failures - * throw ClassCastExceptions during insertions and extractions. - **/ -public class PriorityQueue extends AbstractCollection implements Queue { - public PriorityQueue(int initialCapacity) {} - public PriorityQueue(int initialCapacity, Comparator comparator) {} + * A priority queue based on a priority heap. This queue orders + * elements according to an order specified at construction time, which is + * specified in the same manner as {@link java.util.TreeSet} and + * {@link java.util.TreeMap}: elements are ordered + * either according to their natural order (see {@link Comparable}), or + * according to a {@link java.util.Comparator}, depending on which + * constructor is used. + *

The head of this queue is the least element with + * respect to the specified ordering. + * If multiple elements are tied for least value, the + * head is one of those elements. A priority queue does not permit + * null elements. + * + *

The {@link #remove()} and {@link #poll()} methods remove and + * return the head of the queue. + * + *

The {@link #element()} and {@link #peek()} methods return, but do + * not delete, the head of the queue. + * + *

A priority queue has a capacity. The capacity is the + * size of the array used internally to store the elements on the + * queue, and is limited to Integer.MAX_VALUE-1. + * It is always at least as large as the queue size. As + * elements are added to a priority queue, its capacity grows + * automatically. The details of the growth policy are not specified. + * + *

Implementation note: this implementation provides O(log(n)) time + * for the insertion methods (offer, poll, + * remove() and add) methods; linear time for the + * remove(Object) and contains(Object) methods; and + * constant time for the retrieval methods (peek, + * element, and size). + * + *

This class is a member of the + * + * Java Collections Framework. + * @since 1.5 + * @author Josh Bloch + */ +public class PriorityQueue extends AbstractQueue + implements Sorted, Queue, java.io.Serializable { - public PriorityQueue(int initialCapacity, Collection initialElements) {} + private static final int DEFAULT_INITIAL_CAPACITY = 11; - public PriorityQueue(int initialCapacity, Comparator comparator, Collection initialElements) {} + /** + * Priority queue represented as a balanced binary heap: the two children + * of queue[n] are queue[2*n] and queue[2*n + 1]. The priority queue is + * ordered by comparator, or by the elements' natural ordering, if + * comparator is null: For each node n in the heap and each descendant d + * of n, n <= d. + * + * The element with the lowest value is in queue[1], assuming the queue is + * nonempty. (A one-based array is used in preference to the traditional + * zero-based array to simplify parent and child calculations.) + * + * queue.length must be >= 2, even if size == 0. + */ + private transient Object[] queue; - public boolean add(E x) { - return false; - } - public boolean offer(E x) { - return false; + /** + * The number of elements in the priority queue. + */ + private int size = 0; + + /** + * The comparator, or null if priority queue uses elements' + * natural ordering. + */ + private final Comparator comparator; + + /** + * The number of times this priority queue has been + * structurally modified. See AbstractList for gory details. + */ + private transient int modCount = 0; + + /** + * Create a PriorityQueue with the default initial capacity + * (11) that orders its elements according to their natural + * ordering (using Comparable.) + */ + public PriorityQueue() { + this(DEFAULT_INITIAL_CAPACITY, null); } - public boolean remove(Object x) { - return false; + + /** + * Create a PriorityQueue with the specified initial capacity + * that orders its elements according to their natural ordering + * (using Comparable.) + * + * @param initialCapacity the initial capacity for this priority queue. + */ + public PriorityQueue(int initialCapacity) { + this(initialCapacity, null); } - public E remove() { - return null; + /** + * Create a PriorityQueue with the specified initial capacity + * that orders its elements according to the specified comparator. + * + * @param initialCapacity the initial capacity for this priority queue. + * @param comparator the comparator used to order this priority queue. + * If null then the order depends on the elements' natural + * ordering. + * @throws IllegalArgumentException if initialCapacity is less + * than 1 + */ + public PriorityQueue(int initialCapacity, Comparator comparator) { + if (initialCapacity < 1) + throw new IllegalArgumentException(); + this.queue = new Object[initialCapacity + 1]; + this.comparator = comparator; } - public Iterator iterator() { - return null; + + /** + * Create a PriorityQueue containing the elements in the specified + * collection. The priority queue has an initial capacity of 110% of the + * size of the specified collection (bounded by + * Integer.MAX_VALUE-1); or 1 if the collection is empty. + * If the specified collection + * implements the {@link Sorted} interface, the priority queue will be + * sorted according to the same comparator, or according to its elements' + * natural order if the collection is sorted according to its elements' + * natural order. If the specified collection does not implement + * Sorted, the priority queue is ordered according to + * its elements' natural order. + * + * @param c the collection whose elements are to be placed + * into this priority queue. + * @throws ClassCastException if elements of the specified collection + * cannot be compared to one another according to the priority + * queue's ordering. + * @throws NullPointerException if c or any element within it + * is null + */ + public PriorityQueue(Collection c) { + int sz = c.size(); + int initialCapacity = (int)Math.min((sz * 110L) / 100, + Integer.MAX_VALUE - 1); + if (initialCapacity < 1) + initialCapacity = 1; + + this.queue = new Object[initialCapacity + 1]; + + // FIXME: if c is larger than Integer.MAX_VALUE we'll + // overflow the array + + if (c instanceof Sorted) { + comparator = (Comparator)((Sorted)c).comparator(); + } else { + comparator = null; + } + + for (Iterator i = c.iterator(); i.hasNext(); ) + add(i.next()); } - public E element() { - return null; + // Queue Methods + + /** + * Add the specified element to this priority queue. + * + * @return true + * @throws ClassCastException if the specified element cannot be compared + * with elements currently in the priority queue according + * to the priority queue's ordering. + * @throws NullPointerException if the specified element is null. + */ + public boolean offer(E o) { + if (o == null) + throw new NullPointerException(); + modCount++; + ++size; + + // Grow backing store if necessary + // FIXME: watch for overflow + // FIXME: what if we're full? + while (size >= queue.length) { + Object[] newQueue = new Object[2 * queue.length]; + System.arraycopy(queue, 0, newQueue, 0, queue.length); + queue = newQueue; + } + + queue[size] = o; + fixUp(size); + return true; } + public E poll() { - return null; + if (size == 0) + return null; + return (E) remove(1); } + public E peek() { - return null; + return (E) queue[1]; } - public boolean isEmpty() { + // Collection Methods + + // these first two override just to get the throws docs + + /** + * @throws NullPointerException if the specified element is null. + * @throws ClassCastException if the specified element cannot be compared + * with elements currently in the priority queue according + * to the priority queue's ordering. + */ + public boolean add(E o) { + return super.add(o); + } + + /** + * @throws ClassCastException if any element cannot be compared + * with elements currently in the priority queue according + * to the priority queue's ordering. + * @throws NullPointerException if c or any element in c + * is null + */ + public boolean addAll(Collection c) { + return super.addAll(c); + } + + public boolean remove(Object o) { + if (o == null) + return false; + + if (comparator == null) { + for (int i = 1; i <= size; i++) { + if (((Comparable)queue[i]).compareTo((E)o) == 0) { + remove(i); + return true; + } + } + } else { + for (int i = 1; i <= size; i++) { + if (comparator.compare((E)queue[i], (E)o) == 0) { + remove(i); + return true; + } + } + } return false; } + + public Iterator iterator() { + return new Itr(); + } + + private class Itr implements Iterator { + /** + * Index (into queue array) of element to be returned by + * subsequent call to next. + */ + private int cursor = 1; + + /** + * Index of element returned by most recent call to next or + * previous. Reset to 0 if this element is deleted by a call + * to remove. + */ + private int lastRet = 0; + + /** + * The modCount value that the iterator believes that the backing + * List should have. If this expectation is violated, the iterator + * has detected concurrent modification. + */ + private int expectedModCount = modCount; + + public boolean hasNext() { + return cursor <= size; + } + + public E next() { + checkForComodification(); + if (cursor > size) + throw new NoSuchElementException(); + E result = (E) queue[cursor]; + lastRet = cursor++; + return result; + } + + public void remove() { + if (lastRet == 0) + throw new IllegalStateException(); + checkForComodification(); + + PriorityQueue.this.remove(lastRet); + if (lastRet < cursor) + cursor--; + lastRet = 0; + expectedModCount = modCount; + } + + final void checkForComodification() { + if (modCount != expectedModCount) + throw new ConcurrentModificationException(); + } + } + + /** + * Returns the number of elements in this priority queue. + * + * @return the number of elements in this priority queue. + */ public int size() { - return 0; + return size; } - public Object[] toArray() { - return null; + + /** + * Remove all elements from the priority queue. + */ + public void clear() { + modCount++; + + // Null out element references to prevent memory leak + for (int i=1; i<=size; i++) + queue[i] = null; + + size = 0; } - public T[] toArray(T[] array) { - return null; + /** + * Removes and returns the ith element from queue. Recall + * that queue is one-based, so 1 <= i <= size. + * + * XXX: Could further special-case i==size, but is it worth it? + * XXX: Could special-case i==0, but is it worth it? + */ + private E remove(int i) { + assert i <= size; + modCount++; + + E result = (E) queue[i]; + queue[i] = queue[size]; + queue[size--] = null; // Drop extra ref to prevent memory leak + if (i <= size) + fixDown(i); + return result; + } + + /** + * Establishes the heap invariant (described above) assuming the heap + * satisfies the invariant except possibly for the leaf-node indexed by k + * (which may have a nextExecutionTime less than its parent's). + * + * This method functions by "promoting" queue[k] up the hierarchy + * (by swapping it with its parent) repeatedly until queue[k] + * is greater than or equal to its parent. + */ + private void fixUp(int k) { + if (comparator == null) { + while (k > 1) { + int j = k >> 1; + if (((Comparable)queue[j]).compareTo((E)queue[k]) <= 0) + break; + Object tmp = queue[j]; queue[j] = queue[k]; queue[k] = tmp; + k = j; + } + } else { + while (k > 1) { + int j = k >> 1; + if (comparator.compare((E)queue[j], (E)queue[k]) <= 0) + break; + Object tmp = queue[j]; queue[j] = queue[k]; queue[k] = tmp; + k = j; + } + } + } + + /** + * Establishes the heap invariant (described above) in the subtree + * rooted at k, which is assumed to satisfy the heap invariant except + * possibly for node k itself (which may be greater than its children). + * + * This method functions by "demoting" queue[k] down the hierarchy + * (by swapping it with its smaller child) repeatedly until queue[k] + * is less than or equal to its children. + */ + private void fixDown(int k) { + int j; + if (comparator == null) { + while ((j = k << 1) <= size) { + if (j)queue[j]).compareTo((E)queue[j+1]) > 0) + j++; // j indexes smallest kid + if (((Comparable)queue[k]).compareTo((E)queue[j]) <= 0) + break; + Object tmp = queue[j]; queue[j] = queue[k]; queue[k] = tmp; + k = j; + } + } else { + while ((j = k << 1) <= size) { + if (j < size && comparator.compare((E)queue[j], (E)queue[j+1]) > 0) + j++; // j indexes smallest kid + if (comparator.compare((E)queue[k], (E)queue[j]) <= 0) + break; + Object tmp = queue[j]; queue[j] = queue[k]; queue[k] = tmp; + k = j; + } + } + } + + public Comparator comparator() { + return comparator; + } + + /** + * Save the state of the instance to a stream (that + * is, serialize it). + * + * @serialData The length of the array backing the instance is + * emitted (int), followed by all of its elements (each an + * Object) in the proper order. + * @param s the stream + */ + private synchronized void writeObject(java.io.ObjectOutputStream s) + throws java.io.IOException{ + // Write out element count, and any hidden stuff + s.defaultWriteObject(); + + // Write out array length + s.writeInt(queue.length); + + // Write out all elements in the proper order. + for (int i=0; iArrayList instance from a stream (that is, + * deserialize it). + * @param s the stream + */ + private synchronized void readObject(java.io.ObjectInputStream s) + throws java.io.IOException, ClassNotFoundException { + // Read in size, and any hidden stuff + s.defaultReadObject(); + + // Read in array length and allocate array + int arrayLength = s.readInt(); + queue = new Object[arrayLength]; + + // Read in all elements in the proper order. + for (int i=0; i