java.util
介面 Deque<E>

型別參數：

E - 此 collection 中保存的元素型別

所有父級介面：

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

所有已知子介面：

BlockingDeque<E>

所有已知實作類別：

ArrayDeque, LinkedBlockingDeque, LinkedList

public interface Deque<E>
extends Queue<E>

一個線性 collection，支持在兩端插入和移除元素。名稱 deque 是“double ended queue（雙端佇列）”的縮寫，通常讀為“deck”。大多數 Deque 實作對於它們能夠包含的元素數沒有固定限制，但此介面既支持有容量限制的雙端佇列，也支持沒有固定大小限制的雙端佇列。

此介面定義在雙端佇列兩端存取元素的方法。提供插入、移除和檢查元素的方法。每種方法都存在兩種形式：一種形式在操作失敗時拋出異常，另一種形式返回一個特殊值（null 或 false，具體取決於操作）。插入操作的後一種形式是專為使用有容量限制的 Deque 實作設計的；在大多數實作中，插入操作不能失敗。

下表總結了上述 12 種方法：

	第一個元素（頭部）		最後一個元素（尾部）
	拋出異常	特殊值	拋出異常	特殊值
插入	addFirst(e)	offerFirst(e)	addLast(e)	offerLast(e)
移除	removeFirst()	pollFirst()	removeLast()	pollLast()
檢查	getFirst()	peekFirst()	getLast()	peekLast()

此介面擴展了 Queue 介面。在將雙端佇列用作佇列時，將得到 FIFO（先進先出）行為。將元素添加到雙端佇列的末尾，從雙端佇列的開頭移除元素。從 Queue 介面繼承的方法完全等效於 Deque 方法，如下表所示：

Queue 方法	等效 Deque 方法
add(e)	addLast(e)
offer(e)	offerLast(e)
remove()	removeFirst()
poll()	pollFirst()
element()	getFirst()
peek()	peekFirst()

雙端佇列也可用作 LIFO（後進先出）堆疊(stack)空間。應優先使用此介面而不是遺留 Stack 類別。在將雙端佇列用作堆疊(stack)空間時，元素被推入雙端佇列的開頭並從雙端佇列開頭彈出。堆疊(stack)空間方法完全等效於 Deque 方法，如下表所示：

堆疊(stack)空間方法	等效 Deque 方法
push(e)	addFirst(e)
pop()	removeFirst()
peek()	peekFirst()

注意，在將雙端佇列用作佇列或堆疊(stack)空間時，peek 方法同樣正常工作；無論哪種情況下，都從雙端佇列的開頭抽取元素。

此介面提供了兩種移除內部元素的方法：removeFirstOccurrence 和 removeLastOccurrence。

與 List 介面不同，此介面不支持通過索引存取元素。

雖然 Deque 實作沒有嚴格要求禁止插入 null 元素，但建議最好這樣做。建議任何事實上允許 null 元素的 Deque 實作使用者最好不 要利用插入 null 的功能。這是因為各種方法會將 null 用作特殊的返回值來指示雙端佇列為空。

Deque 實作通常不定義基於元素的 equals 和 hashCode 方法，而是從 Object 類別繼承基於身份的 equals 和 hashCode 方法。

此介面是 Java Collections Framework 的成員。

從以下版本開始：

1.6

方法摘要

boolean	add(E e) 將指定元素插入此雙端佇列所表示的佇列（換句話說，此雙端佇列的尾部），如果可以直接這樣做而不違反容量限制的話；如果成功，則返回 true，如果當前沒有可用空間，則拋出 IllegalStateException。
void	addFirst(E e) 將指定元素插入此雙端佇列的開頭（如果可以直接這樣做而不違反容量限制）。
void	addLast(E e) 將指定元素插入此雙端佇列的末尾（如果可以直接這樣做而不違反容量限制）。
boolean	contains(Object o) 如果此雙端佇列包含指定元素，則返回 true。
Iterator<E>	descendingIterator() 返回以逆向順序在此雙端佇列的元素上進行迭代的迭代器。
E	element() 獲取，但不移除此雙端佇列所表示的佇列的頭部（換句話說，此雙端佇列的第一個元素）。
E	getFirst() 獲取，但不移除此雙端佇列的第一個元素。
E	getLast() 獲取，但不移除此雙端佇列的最後一個元素。
Iterator<E>	iterator() 返回以恰當順序在此雙端佇列的元素上進行迭代的迭代器。
boolean	offer(E e) 將指定元素插入此雙端佇列所表示的佇列（換句話說，此雙端佇列的尾部），如果可以直接這樣做而不違反容量限制的話；如果成功，則返回 true，如果當前沒有可用的空間，則返回 false。
boolean	offerFirst(E e) 在不違反容量限制的情況下，將指定的元素插入此雙端佇列的開頭。
boolean	offerLast(E e) 在不違反容量限制的情況下，將指定的元素插入此雙端佇列的末尾。
E	peek() 獲取，但不移除此雙端佇列所表示的佇列的頭部（換句話說，此雙端佇列的第一個元素）；如果此雙端佇列為空，則返回 null。
E	peekFirst() 獲取，但不移除此雙端佇列的第一個元素；如果此雙端佇列為空，則返回 null。
E	peekLast() 獲取，但不移除此雙端佇列的最後一個元素；如果此雙端佇列為空，則返回 null。
E	poll() 獲取並移除此雙端佇列所表示的佇列的頭部（換句話說，此雙端佇列的第一個元素）；如果此雙端佇列為空，則返回 null。
E	pollFirst() 獲取並移除此雙端佇列的第一個元素；如果此雙端佇列為空，則返回 null。
E	pollLast() 獲取並移除此雙端佇列的最後一個元素；如果此雙端佇列為空，則返回 null。
E	pop() 從此雙端佇列所表示的堆疊(stack)空間中彈出一個元素。
void	push(E e) 將一個元素推入此雙端佇列所表示的堆疊(stack)空間（換句話說，此雙端佇列的頭部），如果可以直接這樣做而不違反容量限制的話；如果成功，則返回 true，如果當前沒有可用空間，則拋出 IllegalStateException。
E	remove() 獲取並移除此雙端佇列所表示的佇列的頭部（換句話說，此雙端佇列的第一個元素）。
boolean	remove(Object o) 從此雙端佇列中移除第一次出現的指定元素。
E	removeFirst() 獲取並移除此雙端佇列第一個元素。
boolean	removeFirstOccurrence(Object o) 從此雙端佇列移除第一次出現的指定元素。
E	removeLast() 獲取並移除此雙端佇列的最後一個元素。
boolean	removeLastOccurrence(Object o) 從此雙端佇列移除最後一次出現的指定元素。
int	size() 返回此雙端佇列的元素數。

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

addAll, clear, containsAll, equals, hashCode, isEmpty, removeAll, retainAll, toArray, toArray

方法詳細資訊

addFirst

void addFirst(E e)

將指定元素插入此雙端佇列的開頭（如果可以直接這樣做而不違反容量限制）。在使用有容量限制的雙端佇列時，通常首選 offerFirst(E) 方法。

參數：

e - 要添加的元素

拋出：

IllegalStateException - 如果此時由於容量限制而無法添加元素

ClassCastException - 如果指定元素的類別不允許將它添加此雙端佇列

NullPointerException - 如果指定元素為 null，並且此雙端佇列不允許 null 元素

IllegalArgumentException - 如果指定元素的某些屬性不允許將它添加到此雙端佇列

addLast

void addLast(E e)

將指定元素插入此雙端佇列的末尾（如果可以直接這樣做而不違反容量限制）。在使用有容量限制的雙端佇列時，通常首選 offerLast(E) 方法。

此方法等效於 add(E)。

參數：

e - 要添加的元素

拋出：

IllegalStateException - 如果此時由於容量限制而無法添加元素

ClassCastException - 如果指定元素的類別不允許將它添加此雙端佇列

NullPointerException - 如果指定元素為 null，並且此雙端佇列不允許 null 元素

IllegalArgumentException - 如果指定元素的某些屬性不允許將它添加到此雙端佇列

offerFirst

boolean offerFirst(E e)

在不違反容量限制的情況下，將指定的元素插入此雙端佇列的開頭。當使用有容量限制的雙端佇列時，此方法通常優於 addFirst(E) 方法，後者可能無法插入元素，而只是拋出一個異常。

參數：

e - 要添加的元素

返回：

如果元素被添加到此雙端佇列，則返回 true，否則返回 false

拋出：

ClassCastException - 如果指定元素的類別不允許將它添加到此雙端佇列

NullPointerException - 如果指定元素為 null，並且此雙端佇列不允許 null 元素

IllegalArgumentException - 如果指定元素的某些屬性不允許將它添加到此雙端佇列

offerLast

boolean offerLast(E e)

在不違反容量限制的情況下，將指定的元素插入此雙端佇列的末尾。當使用有容量限制的雙端佇列時，此方法通常優於 addLast(E) 方法，後者可能無法插入元素，而只是拋出一個異常。

參數：

e - 要添加的元素

返回：

如果元素被添加到此雙端佇列，則返回 true，否則返回 false

拋出：

ClassCastException - 如果指定元素的類別不允許將它添加到此雙端佇列

NullPointerException - 如果指定元素為 null，並且此雙端佇列不允許 null 元素

IllegalArgumentException - 如果指定元素的某些屬性不允許將它添加到此雙端佇列

removeFirst

E removeFirst()

獲取並移除此雙端佇列第一個元素。此方法與 pollFirst 唯一的不同在於：如果此雙端佇列為空，它將拋出一個異常。

返回：

此雙端佇列的頭部

拋出：

NoSuchElementException - 如果此雙端佇列為空

removeLast

E removeLast()

獲取並移除此雙端佇列的最後一個元素。此方法與 pollLast 唯一的不同在於：如果此雙端佇列為空，它將拋出一個異常。

返回：

此雙端佇列的尾部

拋出：

NoSuchElementException - 如果此雙端佇列為空

pollFirst

E pollFirst()

獲取並移除此雙端佇列的第一個元素；如果此雙端佇列為空，則返回 null。

返回：

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

pollLast

E pollLast()

獲取並移除此雙端佇列的最後一個元素；如果此雙端佇列為空，則返回 null。

返回：

此雙端佇列的尾部；如果此雙端佇列為空，則返回 null

getFirst

E getFirst()

獲取，但不移除此雙端佇列的第一個元素。 此方法與 peekFirst 唯一的不同在於：如果此雙端佇列為空，它將拋出一個異常。

返回：

此雙端佇列的頭部

拋出：

NoSuchElementException - 如果此雙端佇列為空

getLast

E getLast()

獲取，但不移除此雙端佇列的最後一個元素。此方法與 peekLast 唯一的不同在於：如果此雙端佇列為空，它將拋出一個異常。

返回：

此雙端佇列的尾部

拋出：

NoSuchElementException - 如果此雙端佇列為空

peekFirst

E peekFirst()

獲取，但不移除此雙端佇列的第一個元素；如果此雙端佇列為空，則返回 null。

返回：

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

peekLast

E peekLast()

獲取，但不移除此雙端佇列的最後一個元素；如果此雙端佇列為空，則返回 null。

返回：

此雙端佇列的尾部；如果此雙端佇列為空，則返回 null

removeFirstOccurrence

boolean removeFirstOccurrence(Object o)

從此雙端佇列移除第一次出現的指定元素。如果此雙端佇列不包含該元素，則不作更改。更確切地講，移除第一個滿足 (o==null ? e==null : o.equals(e)) 的元素 e（如果存在這樣的元素）。如果此雙端佇列包含指定的元素（或者此雙端佇列由於調用而發生了更改），則返回 true。

參數：

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

返回：

如果由於此調用而移除了一個元素，則返回 true

拋出：

ClassCastException - 如果指定元素的類別與此雙端佇列不相容（可選）

NullPointerException - 如果指定元素為 null，並且此雙端佇列不允許 null 元素（可選）

removeLastOccurrence

boolean removeLastOccurrence(Object o)

從此雙端佇列移除最後一次出現的指定元素。如果此雙端佇列不包含該元素，則不作更改。更確切地講，移除最後一個滿足 (o==null ? e==null : o.equals(e)) 的元素 e（如果存在這樣的元素）。如果此雙端佇列包含指定的元素（或者此雙端佇列由於調用而發生了更改），則返回 true。

參數：

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

返回：

如果由於此調用而移除了一個元素，則返回 true

拋出：

ClassCastException - 如果指定元素的類別與此雙端佇列不相容（可選）

NullPointerException - 如果指定元素為 null，並且此雙端佇列不允許 null 元素（可選）

add

boolean add(E e)

將指定元素插入此雙端佇列所表示的佇列（換句話說，此雙端佇列的尾部），如果可以直接這樣做而不違反容量限制的話；如果成功，則返回 true，如果當前沒有可用空間，則拋出 IllegalStateException。當使用有容量限制的雙端佇列時，通常首選 offer。

此方法等效於 addLast(E)。

指定者：

介面 Collection<E> 中的 add

指定者：

介面 Queue<E> 中的 add

參數：

e - 要添加的元素

返回：

true （根據 Collection.add(E) 的規定）

拋出：

IllegalStateException - 如果此時由於容量限制而無法添加元素

ClassCastException - 如果指定元素的類別不允許將它添加到此雙端佇列

NullPointerException - 如果指定元素為 null，並且此雙端佇列不支持 null 元素

IllegalArgumentException - 如果指定元素的某些屬性不允許將它添加到此雙端佇列

offer

boolean offer(E e)

將指定元素插入此雙端佇列所表示的佇列（換句話說，此雙端佇列的尾部），如果可以直接這樣做而不違反容量限制的話；如果成功，則返回 true，如果當前沒有可用的空間，則返回 false。當使用有容量限制的雙端佇列時，此方法通常優於 add(E) 方法，後者可能無法插入元素，而只是拋出一個異常。

此方法等效於 offerLast(E)。

指定者：

介面 Queue<E> 中的 offer

參數：

e - 要添加的元素

返回：

如果元素被添加到此雙端佇列，則返回 true，否則返回 false

拋出：

ClassCastException - 如果指定元素的類別不允許將它添加到此雙端佇列

NullPointerException - 如果指定元素為 null，並且此雙端佇列不允許 null 元素

IllegalArgumentException - 如果指定元素的某些屬性不允許將它添加到此雙端佇列

remove

E remove()

獲取並移除此雙端佇列所表示的佇列的頭部（換句話說，此雙端佇列的第一個元素）。此方法與 poll 的唯一不同在於：如果此雙端佇列為空，它將拋出一個異常。

此方法等效於 removeFirst()。

指定者：

介面 Queue<E> 中的 remove

返回：

此雙端佇列表示的佇列的頭部

拋出：

NoSuchElementException - 如果此雙端佇列為空

poll

E poll()

獲取並移除此雙端佇列所表示的佇列的頭部（換句話說，此雙端佇列的第一個元素）；如果此雙端佇列為空，則返回 null。

此方法等效於 pollFirst()。

指定者：

介面 Queue<E> 中的 poll

返回：

此雙端佇列的第一個元素；如果此雙端佇列為空，則返回 null

element

E element()

獲取，但不移除此雙端佇列所表示的佇列的頭部（換句話說，此雙端佇列的第一個元素）。此方法與 peek 唯一的不同在於：如果此雙端佇列為空，它將拋出一個異常。

此方法等效於 getFirst()。

指定者：

介面 Queue<E> 中的 element

返回：

此雙端佇列表示的佇列的頭部

拋出：

NoSuchElementException - 如果此雙端佇列為空

peek

E peek()

獲取，但不移除此雙端佇列所表示的佇列的頭部（換句話說，此雙端佇列的第一個元素）；如果此雙端佇列為空，則返回 null。

此方法等效於 peekFirst()。

指定者：

介面 Queue<E> 中的 peek

返回：

此雙端佇列所表示的佇列的頭；如果此雙端佇列為空，則返回 null

push

void push(E e)

將一個元素推入此雙端佇列所表示的堆疊(stack)空間（換句話說，此雙端佇列的頭部），如果可以直接這樣做而不違反容量限制的話；如果成功，則返回 true，如果當前沒有可用空間，則拋出 IllegalStateException。

此方法等效於 addFirst(E)。

參數：

e - 要推入的元素

拋出：

IllegalStateException - 如果此時由於容量限制而無法添加元素

ClassCastException - 如果指定元素的類別不允許將它添加此雙端佇列

NullPointerException - 如果指定元素為 null，並且此雙端佇列不允許 null 元素

IllegalArgumentException - 如果指定元素的某些屬性不允許將它添加到此雙端佇列

pop

E pop()

從此雙端佇列所表示的堆疊(stack)空間中彈出一個元素。換句話說，移除並返回此雙端佇列第一個元素。

此方法等效於 removeFirst()。

返回：

此雙端佇列開頭的元素（它是此雙端佇列所表示的堆疊(stack)空間的頂部）

拋出：

NoSuchElementException - 如果此雙端佇列為空

remove

boolean remove(Object o)

從此雙端佇列中移除第一次出現的指定元素。如果此雙端佇列不包含該元素，則不作更改。更確切地講，移除第一個滿足 (o==null ? e==null : o.equals(e)) 的元素 e（如果存在這樣的元素）。如果此雙端佇列包含指定的元素（或者此雙端佇列由於調用而發生了更改），則返回 true。

此方法等效於 removeFirstOccurrence(java.lang.Object)。

指定者：

介面 Collection<E> 中的 remove

參數：

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

返回：

如果由於此調用而移除了一個元素，則返回 true

拋出：

ClassCastException - 如果指定元素的類別與此雙端佇列不相容（可選）

NullPointerException - 如果指定元素為 null，並且此雙端佇列不允許 null 元素（可選）

contains

boolean contains(Object o)

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

指定者：

介面 Collection<E> 中的 contains

參數：

o - 要測試其是否存在於此雙端佇列的元素

返回：

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

拋出：

ClassCastException - 如果指定的元素型別與此雙端佇列不相容（可選）

NullPointerException - 如果指定元素為 null，並且此雙端佇列不允許 null 元素（可選）

size

int size()

返回此雙端佇列的元素數。

指定者：

介面 Collection<E> 中的 size

返回：

此雙端佇列的元素數

iterator

Iterator<E> iterator()

返回以恰當順序在此雙端佇列的元素上進行迭代的迭代器。元素將按從第一個（頭部）到最後一個（尾部）的順序返回。

指定者：

介面 Collection<E> 中的 iterator

指定者：

介面 Iterable<E> 中的 iterator

返回：

按恰當順序在此雙端佇列的元素上進行迭代的迭代器

descendingIterator

Iterator<E> descendingIterator()

返回以逆向順序在此雙端佇列的元素上進行迭代的迭代器。元素將按從最後一個（尾部）到第一個（頭部）的順序返回。

返回：

以逆向順序在此雙端佇列中的元素上進行迭代的迭代器