[cvs] / jsr166 / src / main / java / util / PriorityQueue.java Repository:
ViewVC logotype

Diff of /jsr166/src/main/java/util/PriorityQueue.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

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

Legend:
Removed from v.1.62  
changed lines
  Added in v.1.63

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8