ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/PriorityQueue.java
(Generate patch)

Comparing jsr166/src/main/java/util/PriorityQueue.java (file contents):
Revision 1.62 by jsr166, Thu Feb 16 08:17:21 2006 UTC vs.
Revision 1.63 by jsr166, Tue Mar 7 07:11:39 2006 UTC

# Line 8 | Line 8
8   package java.util;
9  
10   /**
11 < * An unbounded priority {@linkplain Queue queue} based on a priority
12 < * heap.  The elements of the priority queue are ordered according to
13 < * their {@linkplain Comparable natural ordering}, or by a {@link
14 < * Comparator} provided at queue construction time, depending on which
15 < * constructor is used.  A priority queue does not permit
16 < * <tt>null</tt> elements.  A priority queue relying on natural
17 < * ordering also does not permit insertion of non-comparable objects
18 < * (doing so may result in <tt>ClassCastException</tt>).
11 > * An unbounded priority {@linkplain Queue queue} based on a priority heap.
12 > * The elements of the priority queue are ordered according to their
13 > * {@linkplain Comparable natural ordering}, or by a {@link Comparator}
14 > * provided at queue construction time, depending on which constructor is
15 > * used.  A priority queue does not permit {@code null} elements.
16 > * A priority queue relying on natural ordering also does not permit
17 > * insertion of non-comparable objects (doing so may result in
18 > * {@code ClassCastException}).
19   *
20   * <p>The <em>head</em> of this queue is the <em>least</em> element
21   * with respect to the specified ordering.  If multiple elements are
22   * tied for least value, the head is one of those elements -- ties are
23 < * broken arbitrarily.  The queue retrieval operations <tt>poll</tt>,
24 < * <tt>remove</tt>, <tt>peek</tt>, and <tt>element</tt> access the
23 > * broken arbitrarily.  The queue retrieval operations {@code poll},
24 > * {@code remove}, {@code peek}, and {@code element} access the
25   * element at the head of the queue.
26   *
27   * <p>A priority queue is unbounded, but has an internal
# Line 36 | Line 36 | package java.util;
36   * Iterator} interfaces.  The Iterator provided in method {@link
37   * #iterator()} is <em>not</em> guaranteed to traverse the elements of
38   * the priority queue in any particular order. If you need ordered
39 < * traversal, consider using <tt>Arrays.sort(pq.toArray())</tt>.
39 > * traversal, consider using {@code Arrays.sort(pq.toArray())}.
40   *
41   * <p> <strong>Note that this implementation is not synchronized.</strong>
42 < * Multiple threads should not access a <tt>PriorityQueue</tt>
43 < * instance concurrently if any of the threads modifies the list
44 < * structurally. Instead, use the thread-safe {@link
42 > * Multiple threads should not access a {@code PriorityQueue}
43 > * instance concurrently if any of the threads modifies the queue.
44 > * Instead, use the thread-safe {@link
45   * java.util.concurrent.PriorityBlockingQueue} class.
46   *
47 < * <p>Implementation note: this implementation provides O(log(n)) time
48 < * for the insertion methods (<tt>offer</tt>, <tt>poll</tt>,
49 < * <tt>remove()</tt> and <tt>add</tt>) methods; linear time for the
50 < * <tt>remove(Object)</tt> and <tt>contains(Object)</tt> methods; and
51 < * constant time for the retrieval methods (<tt>peek</tt>,
52 < * <tt>element</tt>, and <tt>size</tt>).
47 > * <p>Implementation note: this implementation provides
48 > * O(log(n)) time for the enqueing and dequeing methods
49 > * ({@code offer}, {@code poll}, {@code remove()} and {@code add});
50 > * linear time for the {@code remove(Object)} and {@code contains(Object)}
51 > * methods; and constant time for the retrieval methods
52 > * ({@code peek}, {@code element}, and {@code size}).
53   *
54   * <p>This class is a member of the
55   * <a href="{@docRoot}/../guide/collections/index.html">
56   * Java Collections Framework</a>.
57 + *
58   * @since 1.5
59   * @version %I%, %G%
60 < * @author Josh Bloch
60 > * @author Josh Bloch, Doug Lea
61   * @param <E> the type of elements held in this collection
62   */
63   public class PriorityQueue<E> extends AbstractQueue<E>
# Line 94 | Line 95 | public class PriorityQueue<E> extends Ab
95      private transient int modCount = 0;
96  
97      /**
98 <     * Creates a <tt>PriorityQueue</tt> with the default initial
98 >     * Creates a {@code PriorityQueue} with the default initial
99       * capacity (11) that orders its elements according to their
100       * {@linkplain Comparable natural ordering}.
101       */
# Line 103 | Line 104 | public class PriorityQueue<E> extends Ab
104      }
105  
106      /**
107 <     * Creates a <tt>PriorityQueue</tt> with the specified initial
107 >     * Creates a {@code PriorityQueue} with the specified initial
108       * capacity that orders its elements according to their
109       * {@linkplain Comparable natural ordering}.
110       *
111       * @param initialCapacity the initial capacity for this priority queue
112 <     * @throws IllegalArgumentException if <tt>initialCapacity</tt> is less
113 <     * than 1
112 >     * @throws IllegalArgumentException if {@code initialCapacity} is less
113 >     *         than 1
114       */
115      public PriorityQueue(int initialCapacity) {
116          this(initialCapacity, null);
117      }
118  
119      /**
120 <     * Creates a <tt>PriorityQueue</tt> with the specified initial capacity
120 >     * Creates a {@code PriorityQueue} with the specified initial capacity
121       * that orders its elements according to the specified comparator.
122       *
123       * @param  initialCapacity the initial capacity for this priority queue
124 <     * @param  comparator the comparator that will be used to order
125 <     *         this priority queue.  If <tt>null</tt>, the <i>natural
126 <     *         ordering</i> of the elements will be used.
127 <     * @throws IllegalArgumentException if <tt>initialCapacity</tt> is
124 >     * @param  comparator the comparator that will be used to order this
125 >     *         priority queue.  If {@code null}, the {@linkplain Comparable
126 >     *         natural ordering} of the elements will be used.
127 >     * @throws IllegalArgumentException if {@code initialCapacity} is
128       *         less than 1
129       */
130      public PriorityQueue(int initialCapacity,
# Line 137 | Line 138 | public class PriorityQueue<E> extends Ab
138      }
139  
140      /**
141 <     * Creates a <tt>PriorityQueue</tt> containing the elements in the
142 <     * specified collection.   If the specified collection is an
143 <     * instance of a {@link java.util.SortedSet} or is another
144 <     * <tt>PriorityQueue</tt>, the priority queue will be ordered
145 <     * according to the same ordering.  Otherwise, this priority queue
146 <     * will be ordered according to the natural ordering of its elements.
141 >     * Creates a {@code PriorityQueue} containing the elements in the
142 >     * specified collection.  If the specified collection is an instance of
143 >     * a {@link SortedSet} or is another {@code PriorityQueue}, this
144 >     * priority queue will be ordered according to the same ordering.
145 >     * Otherwise, this priority queue will be ordered according to the
146 >     * {@linkplain Comparable natural ordering} of its elements.
147       *
148       * @param  c the collection whose elements are to be placed
149       *         into this priority queue
# Line 167 | Line 168 | public class PriorityQueue<E> extends Ab
168      }
169  
170      /**
171 <     * Creates a <tt>PriorityQueue</tt> containing the elements in the
171 >     * Creates a {@code PriorityQueue} containing the elements in the
172       * specified priority queue.  This priority queue will be
173       * ordered according to the same ordering as the given priority
174       * queue.
175       *
176       * @param  c the priority queue whose elements are to be placed
177       *         into this priority queue
178 <     * @throws ClassCastException if elements of <tt>c</tt> cannot be
179 <     *         compared to one another according to <tt>c</tt>'s
178 >     * @throws ClassCastException if elements of {@code c} cannot be
179 >     *         compared to one another according to {@code c}'s
180       *         ordering
181       * @throws NullPointerException if the specified priority queue or any
182       *         of its elements are null
# Line 186 | Line 187 | public class PriorityQueue<E> extends Ab
187      }
188  
189      /**
190 <     * Creates a <tt>PriorityQueue</tt> containing the elements in the
191 <     * specified sorted set.  This priority queue will be ordered
190 >     * Creates a {@code PriorityQueue} containing the elements in the
191 >     * specified sorted set.   This priority queue will be ordered
192       * according to the same ordering as the given sorted set.
193       *
194       * @param  c the sorted set whose elements are to be placed
195 <     *         into this priority queue.
195 >     *         into this priority queue
196       * @throws ClassCastException if elements of the specified sorted
197       *         set cannot be compared to one another according to the
198       *         sorted set's ordering
# Line 204 | Line 205 | public class PriorityQueue<E> extends Ab
205      }
206  
207      /**
208 <     * Initialize queue array with elements from the given Collection.
208 >     * Initializes queue array with elements from the given Collection.
209 >     *
210       * @param c the collection
211       */
212      private void initFromCollection(Collection<? extends E> c) {
# Line 239 | Line 241 | public class PriorityQueue<E> extends Ab
241      /**
242       * Inserts the specified element into this priority queue.
243       *
244 <     * @return <tt>true</tt> (as specified by {@link Collection#add})
244 >     * @return {@code true} (as specified by {@link Collection#add})
245       * @throws ClassCastException if the specified element cannot be
246       *         compared with elements currently in this priority queue
247       *         according to the priority queue's ordering
# Line 252 | Line 254 | public class PriorityQueue<E> extends Ab
254      /**
255       * Inserts the specified element into this priority queue.
256       *
257 <     * @return <tt>true</tt> (as specified by {@link Queue#offer})
257 >     * @return {@code true} (as specified by {@link Queue#offer})
258       * @throws ClassCastException if the specified element cannot be
259       *         compared with elements currently in this priority queue
260       *         according to the priority queue's ordering
# Line 290 | Line 292 | public class PriorityQueue<E> extends Ab
292  
293      /**
294       * Removes a single instance of the specified element from this queue,
295 <     * if it is present.  More formally, removes an element <tt>e</tt> such
296 <     * that <tt>o.equals(e)</tt>, if this queue contains one or more such
297 <     * elements.  Returns true if this queue contained the specified element
298 <     * (or equivalently, if this queue changed as a result of the call).
295 >     * if it is present.  More formally, removes an element {@code e} such
296 >     * that {@code o.equals(e)}, if this queue contains one or more such
297 >     * elements.  Returns {@code true} if and only if this queue contained
298 >     * the specified element (or equivalently, if this queue changed as a
299 >     * result of the call).
300       *
301       * @param o element to be removed from this queue, if present
302 <     * @return <tt>true</tt> if this queue changed as a result of the call
302 >     * @return {@code true} if this queue changed as a result of the call
303       */
304      public boolean remove(Object o) {
305          int i = indexOf(o);
# Line 313 | Line 316 | public class PriorityQueue<E> extends Ab
316       * Needed by iterator.remove.
317       *
318       * @param o element to be removed from this queue, if present
319 <     * @return <tt>true</tt> if removed
319 >     * @return {@code true} if removed
320       */
321      boolean removeEq(Object o) {
322          for (int i = 0; i < size; i++) {
# Line 326 | Line 329 | public class PriorityQueue<E> extends Ab
329      }
330  
331      /**
332 <     * Returns <tt>true</tt> if this queue contains the specified element.
333 <     * More formally, returns <tt>true</tt> if and only if this queue contains
334 <     * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>.
332 >     * Returns {@code true} if this queue contains the specified element.
333 >     * More formally, returns {@code true} if and only if this queue contains
334 >     * at least one element {@code e} such that {@code o.equals(e)}.
335       *
336       * @param o object to be checked for containment in this queue
337 <     * @return <tt>true</tt> if this queue contains the specified element
337 >     * @return {@code true} if this queue contains the specified element
338       */
339      public boolean contains(Object o) {
340          return indexOf(o) != -1;
341      }
342  
343      /**
344 <     * Returns an array containing all of the elements in this queue,
344 >     * Returns an array containing all of the elements in this queue.
345       * The elements are in no particular order.
346       *
347       * <p>The returned array will be "safe" in that no references to it are
348 <     * maintained by this list.  (In other words, this method must allocate
348 >     * maintained by this queue.  (In other words, this method must allocate
349       * a new array).  The caller is thus free to modify the returned array.
350       *
351 +     * <p>This method acts as bridge between array-based and collection-based
352 +     * APIs.
353 +     *
354       * @return an array containing all of the elements in this queue
355       */
356      public Object[] toArray() {
# Line 352 | Line 358 | public class PriorityQueue<E> extends Ab
358      }
359  
360      /**
361 <     * Returns an array containing all of the elements in this queue.
362 <     * The elements are in no particular order.  The runtime type of
363 <     * the returned array is that of the specified array.  If the queue
364 <     * fits in the specified array, it is returned therein.
365 <     * Otherwise, a new array is allocated with the runtime type of
366 <     * the specified array and the size of this queue.
361 >     * Returns an array containing all of the elements in this queue; the
362 >     * runtime type of the returned array is that of the specified array.
363 >     * The returned array elements are in no particular order.
364 >     * If the queue fits in the specified array, it is returned therein.
365 >     * Otherwise, a new array is allocated with the runtime type of the
366 >     * specified array and the size of this queue.
367       *
368       * <p>If the queue fits in the specified array with room to spare
369       * (i.e., the array has more elements than the queue), the element in
370       * the array immediately following the end of the collection is set to
371 <     * <tt>null</tt>.  (This is useful in determining the length of the
372 <     * queue <i>only</i> if the caller knows that the queue does not contain
373 <     * any null elements.)
371 >     * {@code null}.
372 >     *
373 >     * <p>Like the {@link #toArray()} method, this method acts as bridge between
374 >     * array-based and collection-based APIs.  Further, this method allows
375 >     * precise control over the runtime type of the output array, and may,
376 >     * under certain circumstances, be used to save allocation costs.
377 >     *
378 >     * <p>Suppose <tt>x</tt> is a queue known to contain only strings.
379 >     * The following code can be used to dump the queue into a newly
380 >     * allocated array of <tt>String</tt>:
381 >     *
382 >     * <pre>
383 >     *     String[] y = x.toArray(new String[0]);</pre>
384 >     *
385 >     * Note that <tt>toArray(new Object[0])</tt> is identical in function to
386 >     * <tt>toArray()</tt>.
387       *
388       * @param a the array into which the elements of the queue are to
389       *          be stored, if it is big enough; otherwise, a new array of the
390       *          same runtime type is allocated for this purpose.
391 <     * @return an array containing the elements of the queue
391 >     * @return an array containing all of the elements in this queue
392       * @throws ArrayStoreException if the runtime type of the specified array
393       *         is not a supertype of the runtime type of every element in
394       *         this queue
# Line 418 | Line 437 | public class PriorityQueue<E> extends Ab
437           * after we've completed the "normal" iteration.
438           *
439           * We expect that most iterations, even those involving removals,
440 <         * will not use need to store elements in this field.
440 >         * will not need to store elements in this field.
441           */
442          private ArrayDeque<E> forgetMeNot = null;
443  
# Line 430 | Line 449 | public class PriorityQueue<E> extends Ab
449  
450          /**
451           * The modCount value that the iterator believes that the backing
452 <         * List should have.  If this expectation is violated, the iterator
452 >         * Queue should have.  If this expectation is violated, the iterator
453           * has detected concurrent modification.
454           */
455          private int expectedModCount = modCount;
# Line 457 | Line 476 | public class PriorityQueue<E> extends Ab
476          public void remove() {
477              if (expectedModCount != modCount)
478                  throw new ConcurrentModificationException();
460            if (lastRet == -1 && lastRetElt == null)
461                throw new IllegalStateException();
479              if (lastRet != -1) {
480                  E moved = PriorityQueue.this.removeAt(lastRet);
481                  lastRet = -1;
# Line 469 | Line 486 | public class PriorityQueue<E> extends Ab
486                          forgetMeNot = new ArrayDeque<E>();
487                      forgetMeNot.add(moved);
488                  }
489 <            } else {
489 >            } else if (lastRetElt != null) {
490                  PriorityQueue.this.removeEq(lastRetElt);
491                  lastRetElt = null;
492 <            }
492 >            } else {
493 >                throw new IllegalStateException();
494 >            }
495              expectedModCount = modCount;
496          }
478
497      }
498  
499      public int size() {
# Line 498 | Line 516 | public class PriorityQueue<E> extends Ab
516              return null;
517          int s = --size;
518          modCount++;
519 <        E result = (E)queue[0];
520 <        E x = (E)queue[s];
519 >        E result = (E) queue[0];
520 >        E x = (E) queue[s];
521          queue[s] = null;
522          if (s != 0)
523              siftDown(0, x);
# Line 516 | Line 534 | public class PriorityQueue<E> extends Ab
534       * i.  Under these circumstances, this method returns the element
535       * that was previously at the end of the list and is now at some
536       * position before i. This fact is used by iterator.remove so as to
537 <     * avoid missing traverseing elements.
537 >     * avoid missing traversing elements.
538       */
539      private E removeAt(int i) {
540          assert i >= 0 && i < size;
# Line 561 | Line 579 | public class PriorityQueue<E> extends Ab
579          while (k > 0) {
580              int parent = (k - 1) >>> 1;
581              Object e = queue[parent];
582 <            if (key.compareTo((E)e) >= 0)
582 >            if (key.compareTo((E) e) >= 0)
583                  break;
584              queue[k] = e;
585              k = parent;
# Line 573 | Line 591 | public class PriorityQueue<E> extends Ab
591          while (k > 0) {
592              int parent = (k - 1) >>> 1;
593              Object e = queue[parent];
594 <            if (comparator.compare(x, (E)e) >= 0)
594 >            if (comparator.compare(x, (E) e) >= 0)
595                  break;
596              queue[k] = e;
597              k = parent;
# Line 604 | Line 622 | public class PriorityQueue<E> extends Ab
622              Object c = queue[child];
623              int right = child + 1;
624              if (right < size &&
625 <                ((Comparable<? super E>)c).compareTo((E)queue[right]) > 0)
625 >                ((Comparable<? super E>) c).compareTo((E) queue[right]) > 0)
626                  c = queue[child = right];
627 <            if (key.compareTo((E)c) <= 0)
627 >            if (key.compareTo((E) c) <= 0)
628                  break;
629              queue[k] = c;
630              k = child;
# Line 621 | Line 639 | public class PriorityQueue<E> extends Ab
639              Object c = queue[child];
640              int right = child + 1;
641              if (right < size &&
642 <                comparator.compare((E)c, (E)queue[right]) > 0)
642 >                comparator.compare((E) c, (E) queue[right]) > 0)
643                  c = queue[child = right];
644 <            if (comparator.compare(x, (E)c) <= 0)
644 >            if (comparator.compare(x, (E) c) <= 0)
645                  break;
646              queue[k] = c;
647              k = child;
# Line 637 | Line 655 | public class PriorityQueue<E> extends Ab
655       */
656      private void heapify() {
657          for (int i = (size >>> 1) - 1; i >= 0; i--)
658 <            siftDown(i, (E)queue[i]);
658 >            siftDown(i, (E) queue[i]);
659      }
660  
661      /**
662       * Returns the comparator used to order the elements in this
663 <     * queue, or <tt>null</tt> if this queue is sorted according to
663 >     * queue, or {@code null} if this queue is sorted according to
664       * the {@linkplain Comparable natural ordering} of its elements.
665       *
666       * @return the comparator used to order this queue, or
667 <     *         <tt>null</tt> if this queue is sorted according to the
668 <     *         natural ordering of its elements.
667 >     *         {@code null} if this queue is sorted according to the
668 >     *         natural ordering of its elements
669       */
670      public Comparator<? super E> comparator() {
671          return comparator;
672      }
673  
674      /**
675 <     * Save the state of the instance to a stream (that
676 <     * is, serialize it).
675 >     * Saves the state of the instance to a stream (that
676 >     * is, serializes it).
677       *
678       * @serialData The length of the array backing the instance is
679 <     * emitted (int), followed by all of its elements (each an
680 <     * <tt>Object</tt>) in the proper order.
679 >     *             emitted (int), followed by all of its elements
680 >     *             (each an {@code Object}) in the proper order.
681       * @param s the stream
682       */
683      private void writeObject(java.io.ObjectOutputStream s)
# Line 667 | Line 685 | public class PriorityQueue<E> extends Ab
685          // Write out element count, and any hidden stuff
686          s.defaultWriteObject();
687  
688 <        // Write out array length
689 <        // For compatibility with 1.5 version, must be at least 2.
672 <        s.writeInt(Math.max(2, queue.length));
688 >        // Write out array length, for compatibility with 1.5 version
689 >        s.writeInt(Math.max(2, size + 1));
690  
691          // Write out all elements in the proper order.
692 <        for (int i=0; i<size; i++)
692 >        for (int i = 0; i < size; i++)
693              s.writeObject(queue[i]);
694      }
695  
696      /**
697 <     * Reconstitute the <tt>PriorityQueue</tt> instance from a stream
698 <     * (that is, deserialize it).
697 >     * Reconstitutes the {@code PriorityQueue} instance from a stream
698 >     * (that is, deserializes it).
699 >     *
700       * @param s the stream
701       */
702      private void readObject(java.io.ObjectInputStream s)
# Line 686 | Line 704 | public class PriorityQueue<E> extends Ab
704          // Read in size, and any hidden stuff
705          s.defaultReadObject();
706  
707 <        // Read in array length and allocate array
708 <        int arrayLength = s.readInt();
709 <        queue = new Object[arrayLength];
707 >        // Read in (and discard) array length
708 >        s.readInt();
709 >
710 >        queue = new Object[size];
711  
712          // Read in all elements in the proper order.
713 <        for (int i=0; i<size; i++)
714 <            queue[i] = (E) s.readObject();
713 >        for (int i = 0; i < size; i++)
714 >            queue[i] = s.readObject();
715      }
697
716   }

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines