--- jsr166/src/main/java/util/PriorityQueue.java 2003/08/05 12:11:08 1.22
+++ jsr166/src/main/java/util/PriorityQueue.java 2003/08/25 23:50:24 1.33
@@ -1,7 +1,8 @@
package java.util;
/**
- * An unbounded priority queue based on a priority heap. This queue orders
+ * An unbounded priority {@linkplain Queue 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
@@ -27,6 +28,18 @@
* elements are added to a priority queue, its capacity grows
* automatically. The details of the growth policy are not specified.
*
+ *
The Iterator provided in method {@link #iterator()} is not
+ * guaranteed to traverse the elements of the PriorityQueue in any
+ * particular order. If you need ordered traversal, consider using
+ * Arrays.sort(pq.toArray()).
+ *
+ *
Note that this implementation is not synchronized.
+ * Multiple threads should not access a PriorityQueue
+ * instance concurrently if any of the threads modifies the list
+ * structurally. Instead, use the thread-safe {@link
+ * java.util.concurrent.BlockingPriorityQueue} class.
+ *
+ *
*
Implementation note: this implementation provides O(log(n)) time
* for the insertion methods (offer, poll,
* remove() and add) methods; linear time for the
@@ -43,6 +56,8 @@
public class PriorityQueue extends AbstractQueue
implements Queue, java.io.Serializable {
+ private static final long serialVersionUID = -7720805057305804111L;
+
private static final int DEFAULT_INITIAL_CAPACITY = 11;
/**
@@ -80,7 +95,7 @@ public class PriorityQueue extends Ab
/**
* Creates a PriorityQueue with the default initial capacity
* (11) that orders its elements according to their natural
- * ordering (using Comparable.)
+ * ordering (using Comparable).
*/
public PriorityQueue() {
this(DEFAULT_INITIAL_CAPACITY, null);
@@ -89,9 +104,11 @@ public class PriorityQueue extends Ab
/**
* Creates a PriorityQueue with the specified initial capacity
* that orders its elements according to their natural ordering
- * (using Comparable.)
+ * (using Comparable).
*
* @param initialCapacity the initial capacity for this priority queue.
+ * @throws IllegalArgumentException if initialCapacity is less
+ * than 1
*/
public PriorityQueue(int initialCapacity) {
this(initialCapacity, null);
@@ -108,7 +125,8 @@ public class PriorityQueue extends Ab
* @throws IllegalArgumentException if initialCapacity is less
* than 1
*/
- public PriorityQueue(int initialCapacity, Comparator super E> comparator) {
+ public PriorityQueue(int initialCapacity,
+ Comparator super E> comparator) {
if (initialCapacity < 1)
throw new IllegalArgumentException();
this.queue = new Object[initialCapacity + 1];
@@ -155,7 +173,7 @@ public class PriorityQueue extends Ab
* specified collection. The priority queue has an initial
* capacity of 110% of the size of the specified collection or 1
* if the collection is empty. If the specified collection is an
- * instance of a {@link SortedSet} or is another
+ * instance of a {@link java.util.SortedSet} or is another
* PriorityQueue, 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
@@ -172,17 +190,16 @@ public class PriorityQueue extends Ab
*/
public PriorityQueue(Collection extends E> c) {
initializeArray(c);
- if (c instanceof SortedSet extends E>) {
- SortedSet extends E> s = (SortedSet extends E>) c;
+ if (c instanceof SortedSet) {
+ // @fixme double-cast workaround for compiler
+ SortedSet extends E> s = (SortedSet extends E>) (SortedSet)c;
comparator = (Comparator super E>)s.comparator();
fillFromSorted(s);
- }
- else if (c instanceof PriorityQueue extends E>) {
+ } else if (c instanceof PriorityQueue) {
PriorityQueue extends E> s = (PriorityQueue extends E>) c;
comparator = (Comparator super E>)s.comparator();
fillFromSorted(s);
- }
- else {
+ } else {
comparator = null;
fillFromUnsorted(c);
}
@@ -256,6 +273,8 @@ public class PriorityQueue extends Ab
// Queue Methods
+
+
/**
* Add the specified element to this priority queue.
*
@@ -290,12 +309,14 @@ public class PriorityQueue extends Ab
return (E) queue[1];
}
- // Collection Methods
-
- // these first two override just to get the throws docs
+ // Collection Methods - the first two override to update docs
/**
- * @throws NullPointerException if the specified element is null.
+ * Adds the specified element to this queue.
+ * @return true (as per the general contract of
+ * Collection.add).
+ *
+ * @throws NullPointerException {@inheritDoc}
* @throws ClassCastException if the specified element cannot be compared
* with elements currently in the priority queue according
* to the priority queue's ordering.
@@ -304,17 +325,40 @@ public class PriorityQueue extends Ab
return super.add(o);
}
+
/**
+ * Adds all of the elements in the specified collection to this queue.
+ * The behavior of this operation is undefined if
+ * the specified collection is modified while the operation is in
+ * progress. (This implies that the behavior of this call is undefined if
+ * the specified collection is this queue, and this queue is nonempty.)
+ *
+ * This implementation iterates over the specified collection, and adds
+ * each object returned by the iterator to this collection, in turn.
+ * @throws NullPointerException {@inheritDoc}
* @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 extends E> c) {
return super.addAll(c);
}
+
+ /**
+ * Removes a single instance of the specified element from this
+ * queue, if it is present. More formally,
+ * removes an element e such that (o==null ? e==null :
+ * o.equals(e)), if the queue contains one or more such
+ * elements. Returns true if the queue contained the
+ * specified element (or equivalently, if the queue changed as a
+ * result of the call).
+ *
+ *
This implementation iterates over the queue looking for the
+ * specified element. If it finds the element, it removes the element
+ * from the queue using the iterator's remove method.
+ *
+ */
public boolean remove(Object o) {
if (o == null)
return false;
@@ -337,6 +381,12 @@ public class PriorityQueue extends Ab
return false;
}
+ /**
+ * Returns an iterator over the elements in this queue. The iterator
+ * does not return the elements in any particular order.
+ *
+ * @return an iterator over the elements in this queue.
+ */
public Iterator iterator() {
return new Itr();
}
@@ -381,8 +431,7 @@ public class PriorityQueue extends Ab
checkForComodification();
PriorityQueue.this.remove(lastRet);
- if (lastRet < cursor)
- cursor--;
+ cursor--;
lastRet = 0;
expectedModCount = modCount;
}
@@ -393,11 +442,6 @@ public class PriorityQueue extends Ab
}
}
- /**
- * Returns the number of elements in this priority queue.
- *
- * @return the number of elements in this priority queue.
- */
public int size() {
return size;
}
@@ -419,8 +463,6 @@ public class PriorityQueue extends Ab
* 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;
@@ -475,7 +517,7 @@ public class PriorityQueue extends Ab
private void fixDown(int k) {
int j;
if (comparator == null) {
- while ((j = k << 1) <= size) {
+ while ((j = k << 1) <= size && (j > 0)) {
if (j)queue[j]).compareTo((E)queue[j+1]) > 0)
j++; // j indexes smallest kid
if (((Comparable)queue[k]).compareTo((E)queue[j]) <= 0)
@@ -484,7 +526,7 @@ public class PriorityQueue extends Ab
k = j;
}
} else {
- while ((j = k << 1) <= size) {
+ while ((j = k << 1) <= size && (j > 0)) {
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)
@@ -495,6 +537,15 @@ public class PriorityQueue extends Ab
}
}
+
+ /**
+ * Returns the comparator used to order this collection, or null
+ * if this collection is sorted according to its elements natural ordering
+ * (using Comparable).
+ *
+ * @return the comparator used to order this collection, or null
+ * if this collection is sorted according to its elements natural ordering.
+ */
public Comparator super E> comparator() {
return comparator;
}