java.util
類別 PriorityQueue<E>

java.lang.Object
  java.util.AbstractCollection<E>
      java.util.AbstractQueue<E>
          java.util.PriorityQueue<E>

型別參數：

E - collection 中所保存元素的型別。

所有已實作的介面：

Serializable, Iterable<E>, Collection<E>, Queue<E>

public class PriorityQueue<E>
extends AbstractQueue<E>
implements Serializable

一個基於優先級堆積(heap)空間的無界優先級佇列。優先級佇列的元素按照其自然順序進行排序，或者根據建構佇列時提供的 Comparator 進行排序，具體取決於所使用的建構子。優先級佇列不允許使用 null 元素。依靠自然順序的優先級佇列還不允許插入不可比較的物件（這樣做可能導致 ClassCastException）。

此佇列的頭 是按指定排序方式確定的最小 元素。如果多個元素都是最小值，則頭是其中一個元素——選擇方法是任意的。佇列獲取操作 poll、remove、peek 和 element 存取處於佇列頭的元素。

優先級佇列是無界的，但是有一個內部容量，控制著用於存儲佇列元素的陣列大小。它通常至少等於佇列的大小。隨著不斷向優先級佇列添加元素，其容量會自動增加。無需指定容量增加策略的細節。

此類別及其迭代器實作了 Collection 和 Iterator 介面的所有可選 方法。方法 iterator() 中提供的迭代器不 保證以任何特定的順序遍歷優先級佇列中的元素。如果需要按順序遍歷，請考慮使用 Arrays.sort(pq.toArray())。

注意，此實作不是同步的。如果多個執行緒中的任意執行緒修改了佇列，則這些執行緒不應同時存取 PriorityQueue 實例。相反，請使用執行緒安全的 PriorityBlockingQueue 類別。

實作注意事項：此實作為排隊和出隊方法（offer、poll、remove() 和 add）提供 O(log(n)) 時間；為 remove(Object) 和 contains(Object) 方法提供線性時間；為獲取方法（peek、element 和 size）提供固定時間。

此類別是 Java Collections Framework 的成員。

從以下版本開始：

1.5

另請參見：

序列化表格

建構子摘要

PriorityQueue()
使用預設的初始容量（11）創建一個 PriorityQueue，並根據其自然順序對元素進行排序。

PriorityQueue(Collection<? extends E> c)
創建包含指定 collection 中元素的 PriorityQueue。

PriorityQueue(int initialCapacity)
使用指定的初始容量創建一個 PriorityQueue，並根據其自然順序對元素進行排序。

PriorityQueue(int initialCapacity, Comparator<? super E> comparator)
使用指定的初始容量創建一個 PriorityQueue，並根據指定的比較器對元素進行排序。

PriorityQueue(PriorityQueue<? extends E> c)
創建包含指定優先級佇列元素的 PriorityQueue。

PriorityQueue(SortedSet<? extends E> c)
創建包含指定有序 set 元素的 PriorityQueue。

方法摘要

boolean	add(E e) 將指定的元素插入此優先級佇列。
void	clear() 從此優先級佇列中移除所有元素。
Comparator<? super E>	comparator() 返回用來對此佇列中的元素進行排序的比較器；如果此佇列根據其元素的自然順序進行排序，則返回 null。
boolean	contains(Object o) 如果此佇列包含指定的元素，則返回 true。
Iterator<E>	iterator() 返回在此佇列中的元素上進行迭代的迭代器。
boolean	offer(E e) 將指定的元素插入此優先級佇列。
E	peek() 獲取但不移除此佇列的頭；如果此佇列為空，則返回 null。
E	poll() 獲取並移除此佇列的頭，如果此佇列為空，則返回 null。
boolean	remove(Object o) 從此佇列中移除指定元素的單個實例（如果存在）。
int	size() 返回此 collection 中的元素數。
Object[]	toArray() 返回一個套件含此佇列所有元素的陣列。
<T> T[]	toArray(T[] a) 返回一個套件含此佇列所有元素的陣列；返回陣列的運行時型別是指定陣列的型別。

從類別 java.util.AbstractQueue 繼承的方法

addAll, element, remove

從類別 java.util.AbstractCollection 繼承的方法

containsAll, isEmpty, removeAll, retainAll, toString

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

從介面 java.util.Collection 繼承的方法

containsAll, equals, hashCode, isEmpty, removeAll, retainAll

建構子詳細資訊

PriorityQueue

public PriorityQueue()

使用預設的初始容量（11）創建一個 PriorityQueue，並根據其自然順序對元素進行排序。

PriorityQueue

public PriorityQueue(int initialCapacity)

使用指定的初始容量創建一個 PriorityQueue，並根據其自然順序對元素進行排序。

參數：

initialCapacity - 此優先級佇列的初始容量

拋出：

IllegalArgumentException - 如果 initialCapacity 小於 1

PriorityQueue

public PriorityQueue(int initialCapacity,
                     Comparator<? super E> comparator)

使用指定的初始容量創建一個 PriorityQueue，並根據指定的比較器對元素進行排序。

參數：

initialCapacity - 此優先級佇列的初始容量

comparator - 用於對此優先級佇列進行排序的比較器。如果該參數為 null，則將使用元素的自然順序

拋出：

IllegalArgumentException - 如果 initialCapacity 小於 1

PriorityQueue

public PriorityQueue(Collection<? extends E> c)

創建包含指定 collection 中元素的 PriorityQueue。如果指定的 collection 是 SortedSet 的一個實例或者是另一個 PriorityQueue，那麼此優先級佇列將根據相同順序進行排序。否則，此優先級佇列將根據元素的自然順序進行排序。

參數：

c - collection，其元素要置於此優先級佇列中

拋出：

ClassCastException - 如果根據優先級佇列的排序規則無法比較指定 collection 中的各個元素

NullPointerException - 如果指定 collection 或任何元素為 null

PriorityQueue

public PriorityQueue(PriorityQueue<? extends E> c)

創建包含指定優先級佇列元素的 PriorityQueue。此優先級佇列將根據與給定優先級佇列相同的順序進行排序。

參數：

c - 優先級佇列，其元素要置於此優先級佇列中

拋出：

ClassCastException - 如果根據 c 的順序無法比較 c 中的各個元素

NullPointerException - 如果指定優先級佇列或任何元素為 null

PriorityQueue

public PriorityQueue(SortedSet<? extends E> c)

創建包含指定有序 set 元素的 PriorityQueue。此優先級佇列將根據與給定有序 set 相同的順序進行排序。

參數：

c - 有序 set，其元素將置於此優先級佇列中

拋出：

ClassCastException - 如果根據有序 set 的順序無法比較該有序 set 中的各個元素

NullPointerException - 如果指定有序 set 或任何元素為 null

方法詳細資訊

add

public boolean add(E e)

將指定的元素插入此優先級佇列。

指定者：

介面 Collection<E> 中的 add

指定者：

介面 Queue<E> 中的 add

覆寫：

類別 AbstractQueue<E> 中的 add

參數：

e - 要添加的元素

返回：

true（正如 Collection.add(E) 所指定的那樣）

拋出：

ClassCastException - 如果根據優先級佇列的順序無法將指定元素與此優先級佇列中當前元素進行比較

NullPointerException - 如果指定的元素為 null

offer

public boolean offer(E e)

將指定的元素插入此優先級佇列。

指定者：

介面 Queue<E> 中的 offer

參數：

e - 要添加的元素

返回：

true（正如 Queue.offer(E) 所指定的那樣）

拋出：

ClassCastException - 如果根據優先級佇列的順序無法將指定元素與此優先級佇列中當前元素進行比較

NullPointerException - 如果指定元素為 null

peek

public E peek()

從介面 Queue 複製的描述

獲取但不移除此佇列的頭；如果此佇列為空，則返回 null。

指定者：

介面 Queue<E> 中的 peek

返回：

此佇列的頭；如果此佇列為空，則返回 null

remove

public boolean remove(Object o)

從此佇列中移除指定元素的單個實例（如果存在）。更確切地講，如果此佇列包含一個或多個滿足 o.equals(e) 的元素 e，則移除一個這樣的元素。當且僅當此佇列包含指定的元素（或者此佇列由於調用而發生更改），則返回 true。

指定者：

介面 Collection<E> 中的 remove

覆寫：

類別 AbstractCollection<E> 中的 remove

參數：

o - 要從此佇列中移除的元素（如果存在）

返回：

如果此佇列由於調用而發生更改，則返回 true

contains

public boolean contains(Object o)

如果此佇列包含指定的元素，則返回 true。更確切地講，當且僅當此佇列至少包含一個滿足 o.equals(e) 的元素 e 時，才返回 true。

指定者：

介面 Collection<E> 中的 contains

覆寫：

類別 AbstractCollection<E> 中的 contains

參數：

o - 要檢查是否包含於此佇列的物件

返回：

如果此佇列包含指定元素，則返回 true

toArray

public Object[] toArray()

返回一個套件含此佇列所有元素的陣列。陣列元素沒有特定的順序。

由於此佇列並不維護對返回陣列的任何參考，因而它將是「安全的」。（換句話說，此方法必須分派一個新陣列）。因此，調用者可以隨意修改返回的陣列。

此方法充當基於陣列的 API 與基於 collection 的 API 之間的橋樑。

指定者：

介面 Collection<E> 中的 toArray

覆寫：

類別 AbstractCollection<E> 中的 toArray

返回：

包含此佇列所有元素的陣列

toArray

public <T> T[] toArray(T[] a)

返回一個套件含此佇列所有元素的陣列；返回陣列的運行時型別是指定陣列的型別。返回陣列的元素沒有特定的順序。如果指定的陣列能容納佇列，則將該佇列返回此處。否則，將根據指定陣列的運行時型別和此佇列的大小分派一個新陣列。

如果指定陣列能容納佇列，且有剩餘空間（即陣列比佇列元素多），則緊跟在 collection 末尾的陣列元素將被設置為 null。

像 toArray() 方法一樣，此方法充當基於陣列 的 API 與基於 collection 的 API 之間的橋樑。進一步說，此方法允許對輸出陣列的運行時型別進行精確控制，在某些情況下，可以用來節省分派開銷。

假定 x 是只包含字元串的一個已知佇列。以下程式碼可以用來將該佇列轉儲到一個新分派的 String 陣列：

     String[] y = x.toArray(new String[0]);

注意，toArray(new Object[0]) 和 toArray() 在功能上是相同的。

指定者：

介面 Collection<E> 中的 toArray

覆寫：

類別 AbstractCollection<E> 中的 toArray

參數：

a - 存儲此佇列元素的陣列（如果該陣列足夠大）；否則，將為此分派一個具有相同運行時型別的新陣列。

返回：

包含此佇列所有元素的陣列

拋出：

如果指定陣列的運行時型別不是此佇列每個元素的運行時型別的子型別

NullPointerException - 如果指定陣列為 null

iterator

public Iterator<E> iterator()

返回在此佇列中的元素上進行迭代的迭代器。迭代器並不以任意特定的順序返回元素。

指定者：

介面 Iterable<E> 中的 iterator

指定者：

介面 Collection<E> 中的 iterator

指定者：

類別 AbstractCollection<E> 中的 iterator

返回：

在此佇列的元素上進行迭代的迭代器

size

public int size()

從介面 Collection 複製的描述

返回此 collection 中的元素數。如果此 collection 套件含的元素大於 Integer.MAX_VALUE，則返回 Integer.MAX_VALUE。

指定者：

介面 Collection<E> 中的 size

指定者：

類別 AbstractCollection<E> 中的 size

返回：

此 collection 中的元素數

clear

public void clear()

從此優先級佇列中移除所有元素。此調用返回後佇列為空。

指定者：

介面 Collection<E> 中的 clear

覆寫：

類別 AbstractQueue<E> 中的 clear

poll

public E poll()

從介面 Queue 複製的描述

獲取並移除此佇列的頭，如果此佇列為空，則返回 null。

指定者：

介面 Queue<E> 中的 poll

返回：

佇列的頭，如果此佇列為空，則返回 null

comparator

public Comparator<? super E> comparator()

返回用來對此佇列中的元素進行排序的比較器；如果此佇列根據其元素的自然順序進行排序，則返回 null。

返回：

用於對此佇列進行排序的比較器；如果此佇列根據其元素的自然順序進行排序，則返回 null