sample/java.util.PriorityQueue.txt

   1 *java.util.PriorityQueue* *PriorityQueue* An unbounded priorityQueue queuebased
   2
   3 public class PriorityQueue<E>
   4   extends    |java.util.AbstractQueue|
   5   implements |java.io.Serializable|
   6
   7 |java.util.PriorityQueue_Description|
   8 |java.util.PriorityQueue_Fields|
   9 |java.util.PriorityQueue_Constructors|
  10 |java.util.PriorityQueue_Methods|
  11
  12 ================================================================================
  13
  14 *java.util.PriorityQueue_Constructors*
  15 |java.util.PriorityQueue()|Creates aPriorityQueuewith the default initial  capa
  16 |java.util.PriorityQueue(Collection<?extendsE>)|Creates aPriorityQueuecontainin
  17 |java.util.PriorityQueue(int)|Creates aPriorityQueuewith the specified initial
  18 |java.util.PriorityQueue(int,Comparator<?superE>)|Creates aPriorityQueuewith th
  19 |java.util.PriorityQueue(PriorityQueue<?extendsE>)|Creates aPriorityQueuecontai
  20 |java.util.PriorityQueue(SortedSet<?extendsE>)|Creates aPriorityQueuecontaining
  21
  22 *java.util.PriorityQueue_Methods*
  23 |java.util.PriorityQueue.add(E)|Inserts the specified element into this priorit
  24 |java.util.PriorityQueue.clear()|Removes all of the elements from this priority
  25 |java.util.PriorityQueue.comparator()|Returns the comparator used to order the
  26 |java.util.PriorityQueue.contains(Object)|Returnstrueif this queue contains the
  27 |java.util.PriorityQueue.iterator()|Returns an iterator over the elements in th
  28 |java.util.PriorityQueue.offer(E)|Inserts the specified element into this prior
  29 |java.util.PriorityQueue.peek()|
  30 |java.util.PriorityQueue.poll()|
  31 |java.util.PriorityQueue.remove(Object)|Removes a single instance of the specif
  32 |java.util.PriorityQueue.size()|
  33 |java.util.PriorityQueue.toArray()|Returns an array containing all of the eleme
  34 |java.util.PriorityQueue.toArray(T[])|Returns an array containing all of the el
  35
  36 *java.util.PriorityQueue_Description*
  37
  38 An unbounded priority queue(|java.util.Queue|) based on a priority heap. The
  39 elements of the priority queue are ordered according to their natural
  40 ordering(|java.lang.Comparable|) , or by a (|java.util.Comparator|) provided at
  41 queue construction time, depending on which constructor is used. A priority
  42 queue does not permitnullelements. A priority queue relying on natural ordering
  43 also does not permit insertion of non-comparable objects (doing so may result
  44 inClassCastException).
  45
  46 The head of this queue is the least element with respect to the specified
  47 ordering. If multiple elements are tied for least value, the head is one of
  48 those elements -- ties are broken arbitrarily. The queue retrieval
  49 operationspoll,remove,peek, andelementaccess the element at the head of the
  50 queue.
  51
  52 A priority queue is unbounded, but has an internal capacity governing the size
  53 of an array used to store the elements on the queue. It is always at least as
  54 large as the queue size. As elements are added to a priority queue, its
  55 capacity grows automatically. The details of the growth policy are not
  56 specified.
  57
  58 This class and its iterator implement all of the optional methods of the
  59 (|java.util.Collection|) and (|java.util.Iterator|) interfaces. The Iterator
  60 provided in method (|java.util.PriorityQueue|) is not guaranteed to traverse
  61 the elements of the priority queue in any particular order. If you need ordered
  62 traversal, consider usingArrays.sort(pq.toArray()).
  63
  64 Note that this implementation is not synchronized. Multiple threads should not
  65 access aPriorityQueueinstance concurrently if any of the threads modifies the
  66 queue. Instead, use the thread-safe
  67 (|java.util.concurrent.PriorityBlockingQueue|) class.
  68
  69 Implementation note: this implementation provides O(log(n)) time for the
  70 enqueing and dequeing methods (offer,poll,remove()andadd); linear time for
  71 theremove(Object)andcontains(Object)methods; and constant time for the
  72 retrieval methods (peek,element, andsize).
  73
  74 This class is a member of the <a
  75 href="/../technotes/guides/collections/index.html"> Java Collections Framework.
  76
  77
  78
  79 *java.util.PriorityQueue()*
  80
  81 public PriorityQueue()
  82
  83 Creates aPriorityQueuewith the default initial capacity (11) that orders its
  84 elements according to their natural ordering(|java.lang.Comparable|) .
  85
  86
  87 *java.util.PriorityQueue(Collection<?extendsE>)*
  88
  89 public PriorityQueue(java.util.Collection<? extends E> c)
  90
  91 Creates aPriorityQueuecontaining the elements in the specified collection. If
  92 the specified collection is an instance of a (|java.util.SortedSet|) or is
  93 anotherPriorityQueue, this priority queue will be ordered according to the same
  94 ordering. Otherwise, this priority queue will be ordered according to the
  95 natural ordering(|java.lang.Comparable|) of its elements.
  96
  97     c - the collection whose elements are to be placed into this priority queue
  98
  99 *java.util.PriorityQueue(int)*
 100
 101 public PriorityQueue(int initialCapacity)
 102
 103 Creates aPriorityQueuewith the specified initial capacity that orders its
 104 elements according to their natural ordering(|java.lang.Comparable|) .
 105
 106     initialCapacity - the initial capacity for this priority queue
 107
 108 *java.util.PriorityQueue(int,Comparator<?superE>)*
 109
 110 public PriorityQueue(
 111   int initialCapacity,
 112   java.util.Comparator<? super E> comparator)
 113
 114 Creates aPriorityQueuewith the specified initial capacity that orders its
 115 elements according to the specified comparator.
 116
 117     initialCapacity - the initial capacity for this priority queue
 118     comparator - the comparator that will be used to order this priority queue. If {@code null},
 119        the {@linkplain Comparable natural ordering} of the elements will be
 120        used.
 121
 122 *java.util.PriorityQueue(PriorityQueue<?extendsE>)*
 123
 124 public PriorityQueue(java.util.PriorityQueue<? extends E> c)
 125
 126 Creates aPriorityQueuecontaining the elements in the specified priority queue.
 127 This priority queue will be ordered according to the same ordering as the given
 128 priority queue.
 129
 130     c - the priority queue whose elements are to be placed into this priority queue
 131
 132 *java.util.PriorityQueue(SortedSet<?extendsE>)*
 133
 134 public PriorityQueue(java.util.SortedSet<? extends E> c)
 135
 136 Creates aPriorityQueuecontaining the elements in the specified sorted set. This
 137 priority queue will be ordered according to the same ordering as the given
 138 sorted set.
 139
 140     c - the sorted set whose elements are to be placed into this priority queue
 141
 142 *java.util.PriorityQueue.add(E)*
 143
 144 public boolean add(E e)
 145
 146 Inserts the specified element into this priority queue.
 147
 148
 149
 150     Returns: {@code true} (as specified by {@link Collection#add})
 151
 152 *java.util.PriorityQueue.clear()*
 153
 154 public void clear()
 155
 156 Removes all of the elements from this priority queue. The queue will be empty
 157 after this call returns.
 158
 159
 160
 161 *java.util.PriorityQueue.comparator()*
 162
 163 public |java.util.Comparator|<? super E> comparator()
 164
 165 Returns the comparator used to order the elements in this queue, ornullif this
 166 queue is sorted according to the natural ordering(|java.lang.Comparable|) of
 167 its elements.
 168
 169
 170
 171     Returns: the comparator used to order this queue, or {@code null} if this queue is
 172              sorted according to the natural ordering of its elements
 173
 174 *java.util.PriorityQueue.contains(Object)*
 175
 176 public boolean contains(java.lang.Object o)
 177
 178 Returnstrueif this queue contains the specified element. More formally,
 179 returnstrueif and only if this queue contains at least one elementesuch
 180 thato.equals(e).
 181
 182
 183     o - object to be checked for containment in this queue
 184
 185     Returns: {@code true} if this queue contains the specified element
 186
 187 *java.util.PriorityQueue.iterator()*
 188
 189 public |java.util.Iterator|<E> iterator()
 190
 191 Returns an iterator over the elements in this queue. The iterator does not
 192 return the elements in any particular order.
 193
 194
 195
 196     Returns: an iterator over the elements in this queue
 197
 198 *java.util.PriorityQueue.offer(E)*
 199
 200 public boolean offer(E e)
 201
 202 Inserts the specified element into this priority queue.
 203
 204
 205
 206     Returns: {@code true} (as specified by {@link Queue#offer})
 207
 208 *java.util.PriorityQueue.peek()*
 209
 210 public |E| peek()
 211
 212
 213
 214
 215
 216 *java.util.PriorityQueue.poll()*
 217
 218 public |E| poll()
 219
 220
 221
 222
 223
 224 *java.util.PriorityQueue.remove(Object)*
 225
 226 public boolean remove(java.lang.Object o)
 227
 228 Removes a single instance of the specified element from this queue, if it is
 229 present. More formally, removes an elementesuch thato.equals(e), if this queue
 230 contains one or more such elements. Returnstrueif and only if this queue
 231 contained the specified element (or equivalently, if this queue changed as a
 232 result of the call).
 233
 234
 235     o - element to be removed from this queue, if present
 236
 237     Returns: {@code true} if this queue changed as a result of the call
 238
 239 *java.util.PriorityQueue.size()*
 240
 241 public int size()
 242
 243
 244
 245
 246
 247 *java.util.PriorityQueue.toArray()*
 248
 249 public |java.lang.Object|[] toArray()
 250
 251 Returns an array containing all of the elements in this queue. The elements are
 252 in no particular order.
 253
 254 The returned array will be "safe" in that no references to it are maintained by
 255 this queue. (In other words, this method must allocate a new array). The caller
 256 is thus free to modify the returned array.
 257
 258 This method acts as bridge between array-based and collection-based APIs.
 259
 260
 261
 262     Returns: an array containing all of the elements in this queue
 263
 264 *java.util.PriorityQueue.toArray(T[])*
 265
 266 public |T|[] toArray(T[] a)
 267
 268 Returns an array containing all of the elements in this queue; the runtime type
 269 of the returned array is that of the specified array. The returned array
 270 elements are in no particular order. If the queue fits in the specified array,
 271 it is returned therein. Otherwise, a new array is allocated with the runtime
 272 type of the specified array and the size of this queue.
 273
 274 If the queue fits in the specified array with room to spare (i.e., the array
 275 has more elements than the queue), the element in the array immediately
 276 following the end of the collection is set tonull.
 277
 278 Like the (|java.util.PriorityQueue|) method, this method acts as bridge between
 279 array-based and collection-based APIs. Further, this method allows precise
 280 control over the runtime type of the output array, and may, under certain
 281 circumstances, be used to save allocation costs.
 282
 283 Suppose x is a queue known to contain only strings. The following code can be
 284 used to dump the queue into a newly allocated array of String:
 285
 286
 287
 288 String[] y = x.toArray(new String[0]);
 289
 290 Note that toArray(new Object[0]) is identical in function to toArray().
 291
 292
 293     a - the array into which the elements of the queue are to be stored, if it is big
 294        enough; otherwise, a new array of the same runtime type is allocated for
 295        this purpose.
 296
 297     Returns: an array containing all of the elements in this queue
 298
 299