--- jsr166/src/main/java/util/PriorityQueue.java 2003/09/07 15:06:19 1.39 +++ jsr166/src/main/java/util/PriorityQueue.java 2003/10/19 13:38:29 1.45 @@ -8,31 +8,33 @@ package java.util; /** - * 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 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. + * 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 either according to their + * natural order (see {@link Comparable}), or according to a + * {@link java.util.Comparator}, depending on which constructor is + * used. A priority queue does not permit null elements. + * A priority queue relying on natural ordering also does not + * permit insertion of non-comparable objects (doing so may result + * in ClassCastException). * - *

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

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 -- ties are + * broken arbitrarily. The queue retrieval operations poll, + * remove, peek, and element access the + * element at 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 is unbounded, but has an internal + * capacity governing the size of an array used to store the + * elements on the queue. 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. * - *

A priority queue has a capacity. The capacity is the - * size of the array used internally to store the elements on the - * queue. - * 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. - * - *

The Iterator provided in method {@link #iterator()} is not + *

This class implements all of the optional methods of + * the {@link Collection} and {@link Iterator} interfaces. 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()). @@ -57,6 +59,7 @@ package java.util; * @since 1.5 * @version %I%, %G% * @author Josh Bloch + * @param the type of elements held in this collection */ public class PriorityQueue extends AbstractQueue implements Queue, java.io.Serializable { @@ -277,10 +280,8 @@ public class PriorityQueue extends Ab } - // Queue Methods - /** - * Add the specified element to this priority queue. + * Inserts the specified element into this priority queue. * * @return true * @throws ClassCastException if the specified element cannot be compared @@ -303,13 +304,9 @@ public class PriorityQueue extends Ab return true; } - public E poll() { + public E peek() { if (size == 0) return null; - return remove(); - } - - public E peek() { return (E) queue[1]; } @@ -320,49 +317,15 @@ public class PriorityQueue extends Ab * @return true (as per the general contract of * Collection.add). * - * @throws NullPointerException {@inheritDoc} + * @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); + return offer(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. - */ - public boolean addAll(Collection 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; @@ -506,12 +469,9 @@ public class PriorityQueue extends Ab size = 0; } - /** - * Removes and returns the first element from queue. - */ - public E remove() { + public E poll() { if (size == 0) - throw new NoSuchElementException(); + return null; modCount++; E result = (E) queue[1];