java.util
類別 ArrayDeque<E>

java.lang.Object
  java.util.AbstractCollection<E>
      java.util.ArrayDeque<E>

型別參數：

E - the type of elements held in this collection

所有已實作的介面：

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

public class ArrayDeque<E>
extends AbstractCollection<E>
implements Deque<E>, Cloneable, Serializable

Deque 介面的大小可變陣列的實作。陣列雙端佇列沒有容量限制；它們可根據需要增加以支持使用。它們不是執行緒安全的；在沒有外部同步時，它們不支持多個執行緒的共時存取。禁止 null 元素。此類別很可能在用作堆疊(stack)空間時快於 Stack，在用作佇列時快於 LinkedList。

大多數 ArrayDeque 操作以攤銷的固定時間運行。異常包括 remove、removeFirstOccurrence、removeLastOccurrence、contains、iterator.remove() 以及批量操作，它們均以線性時間運行。

此類別的 iterator 方法返回的迭代器是快速失敗 的：如果在創建迭代器後的任意時間通過除迭代器本身的 remove 方法之外的任何其他方式修改了雙端佇列，則迭代器通常將拋出 ConcurrentModificationException。因此，面對共時修改，迭代器很快就會完全失敗，而不是冒著在將來不確定的時刻任意發生不確定行為的風險。

注意，迭代器的快速失敗行為不能得到保證，一般來說，存在不同步的共時修改時，不可能作出任何堅決的保證。快速失敗迭代器盡最大努力拋出 ConcurrentModificationException。因此，編寫依賴於此異常的程序是錯誤的，正確做法是：迭代器的快速失敗行為應該僅用於檢測 bug。

此類別及其迭代器實作 Collection 和 Iterator 介面的所有可選 方法。

此類別是 Java Collections Framework 的成員。

從以下版本開始：

1.6

另請參見：

序列化表格

建構子摘要

ArrayDeque()
建構一個初始容量能夠容納 16 個元素的空陣列雙端佇列。

ArrayDeque(Collection<? extends E> c)
建構一個套件含指定 collection 的元素的雙端佇列，這些元素按 collection 的迭代器返回的順序排列。

ArrayDeque(int numElements)
建構一個初始容量能夠容納指定數量的元素的空陣列雙端佇列。

方法摘要

boolean	add(E e) 將指定元素插入此雙端佇列的末尾。
void	addFirst(E e) 將指定元素插入此雙端佇列的開頭。
void	addLast(E e) 將指定元素插入此雙端佇列的末尾。
void	clear() 從此雙端佇列中移除所有元素。
ArrayDeque<E>	clone() 返回此雙端佇列的副本。
boolean	contains(Object o) 如果此雙端佇列包含指定元素，則返回 true。
Iterator<E>	descendingIterator() 返回以逆向順序在此雙端佇列的元素上進行迭代的迭代器。
E	element() 獲取，但不移除此雙端佇列所表示的佇列的頭。
E	getFirst() 獲取，但不移除此雙端佇列的第一個元素。
E	getLast() 獲取，但不移除此雙端佇列的最後一個元素。
boolean	isEmpty() 如果此雙端佇列未包含任何元素，則返回 true。
Iterator<E>	iterator() 返回在此雙端佇列的元素上進行迭代的迭代器。
boolean	offer(E e) 將指定元素插入此雙端佇列的末尾。
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)空間。
E	remove() 獲取並移除此雙端佇列所表示的佇列的頭。
boolean	remove(Object o) 從此雙端佇列中移除指定元素的單個實例。
E	removeFirst() 獲取並移除此雙端佇列第一個元素。
boolean	removeFirstOccurrence(Object o) 移除此雙端佇列中第一次出現的指定元素（當從頭部到尾部遍歷雙端佇列時）。
E	removeLast() 獲取並移除此雙端佇列的最後一個元素。
boolean	removeLastOccurrence(Object o) 移除此雙端佇列中最後一次出現的指定元素（當從頭部到尾部遍歷雙端佇列時）。
int	size() 返回此雙端佇列中的元素數。
Object[]	toArray() 返回一個以恰當順序包含此雙端佇列所有元素的陣列（從第一個元素到最後一個元素）。
<T> T[]	toArray(T[] a) 返回一個以恰當順序包含此雙端佇列所有元素的陣列（從第一個元素到最後一個元素）；返回陣列的運行時型別是指定陣列的運行時型別。

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

addAll, containsAll, removeAll, retainAll, toString

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

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

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

addAll, containsAll, equals, hashCode, removeAll, retainAll

建構子詳細資訊

ArrayDeque

public ArrayDeque()

建構一個初始容量能夠容納 16 個元素的空陣列雙端佇列。

ArrayDeque

public ArrayDeque(int numElements)

建構一個初始容量能夠容納指定數量的元素的空陣列雙端佇列。

參數：

numElements - 雙端佇列初始容量的下邊界

ArrayDeque

public ArrayDeque(Collection<? extends E> c)

建構一個套件含指定 collection 的元素的雙端佇列，這些元素按 collection 的迭代器返回的順序排列。（collection 迭代器返回的第一個元素將是第一個元素，或雙端佇列的開頭。）

參數：

c - 要將其元素放入雙端佇列的 collection

拋出：

NullPointerException - 如果指定 collection 為 null

方法詳細資訊

addFirst

public void addFirst(E e)

將指定元素插入此雙端佇列的開頭。

指定者：

介面 Deque<E> 中的 addFirst

參數：

e - 要添加的元素

拋出：

NullPointerException - 如果指定元素為 null

addLast

public void addLast(E e)

將指定元素插入此雙端佇列的末尾。

此方法等效於 add(E)。

指定者：

介面 Deque<E> 中的 addLast

參數：

e - 要添加的元素

拋出：

NullPointerException - 如果指定元素為 null

offerFirst

public boolean offerFirst(E e)

將指定元素插入此雙端佇列的開頭。

指定者：

介面 Deque<E> 中的 offerFirst

參數：

e - 要添加的元素

返回：

true （根據 Deque.offerFirst(E) 的規定）

拋出：

NullPointerException - 如果指定元素為 null

offerLast

public boolean offerLast(E e)

將指定元素插入此雙端佇列的末尾。

指定者：

介面 Deque<E> 中的 offerLast

參數：

e - 要添加的元素

返回：

true （根據 Deque.offerLast(E) 的規定）

拋出：

NullPointerException - 如果指定元素為 null

removeFirst

public E removeFirst()

從介面 Deque 複製的描述

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

指定者：

介面 Deque<E> 中的 removeFirst

返回：

此雙端佇列的頭部

拋出：

NoSuchElementException - 如果此雙端佇列為空

removeLast

public E removeLast()

從介面 Deque 複製的描述

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

指定者：

介面 Deque<E> 中的 removeLast

返回：

此雙端佇列的尾部

拋出：

NoSuchElementException - 如果此雙端佇列為空

pollFirst

public E pollFirst()

從介面 Deque 複製的描述

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

指定者：

介面 Deque<E> 中的 pollFirst

返回：

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

pollLast

public E pollLast()

從介面 Deque 複製的描述

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

指定者：

介面 Deque<E> 中的 pollLast

返回：

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

getFirst

public E getFirst()

從介面 Deque 複製的描述

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

指定者：

介面 Deque<E> 中的 getFirst

返回：

此雙端佇列的頭部

拋出：

NoSuchElementException - 如果此雙端佇列為空

getLast

public E getLast()

從介面 Deque 複製的描述

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

指定者：

介面 Deque<E> 中的 getLast

返回：

此雙端佇列的尾部

拋出：

NoSuchElementException - 如果此雙端佇列為空

peekFirst

public E peekFirst()

從介面 Deque 複製的描述

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

指定者：

介面 Deque<E> 中的 peekFirst

返回：

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

peekLast

public E peekLast()

從介面 Deque 複製的描述

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

指定者：

介面 Deque<E> 中的 peekLast

返回：

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

removeFirstOccurrence

public boolean removeFirstOccurrence(Object o)

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

指定者：

介面 Deque<E> 中的 removeFirstOccurrence

參數：

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

返回：

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

removeLastOccurrence

public boolean removeLastOccurrence(Object o)

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

指定者：

介面 Deque<E> 中的 removeLastOccurrence

參數：

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

返回：

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

add

public boolean add(E e)

將指定元素插入此雙端佇列的末尾。

此方法等效於 addLast(E)。

指定者：

介面 Collection<E> 中的 add

指定者：

介面 Deque<E> 中的 add

指定者：

介面 Queue<E> 中的 add

覆寫：

類別 AbstractCollection<E> 中的 add

參數：

e - 要添加的元素

返回：

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

拋出：

NullPointerException - 如果指定元素為 null

offer

public boolean offer(E e)

將指定元素插入此雙端佇列的末尾。

此方法等效於 offerLast(E)。

指定者：

介面 Deque<E> 中的 offer

指定者：

介面 Queue<E> 中的 offer

參數：

e - 要添加的元素

返回：

true（根據 Queue.offer(E) 的規定）

拋出：

NullPointerException - 如果指定元素為 null

remove

public E remove()

獲取並移除此雙端佇列所表示的佇列的頭。 此方法與 poll 的不同之處在於：如果此雙端佇列為空，它將拋出一個異常。

此方法等效於 removeFirst()。

指定者：

介面 Deque<E> 中的 remove

指定者：

介面 Queue<E> 中的 remove

返回：

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

拋出：

NoSuchElementException - 如果此雙端佇列為空

poll

public E poll()

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

此方法等效於 pollFirst()。

指定者：

介面 Deque<E> 中的 poll

指定者：

介面 Queue<E> 中的 poll

返回：

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

element

public E element()

獲取，但不移除此雙端佇列所表示的佇列的頭。此方法與 peek 的不同之處在於：如果此雙端佇列為空，它將拋出一個異常。

此方法等效於 getFirst()。

指定者：

介面 Deque<E> 中的 element

指定者：

介面 Queue<E> 中的 element

返回：

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

拋出：

NoSuchElementException - 如果此雙端佇列為空

peek

public E peek()

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

此方法等效於 peekFirst()。

指定者：

介面 Deque<E> 中的 peek

指定者：

介面 Queue<E> 中的 peek

返回：

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

push

public void push(E e)

將元素推入此雙端佇列所表示的堆疊(stack)空間。換句話說，將元素插入此雙端佇列的開頭。

此方法等效於 addFirst(E)。

指定者：

介面 Deque<E> 中的 push

參數：

e - 要推入的元素

拋出：

NullPointerException - 如果指定元素為 null

pop

public E pop()

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

此方法等效於 removeFirst()。

指定者：

介面 Deque<E> 中的 pop

返回：

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

拋出：

NoSuchElementException - 如果此雙端佇列為空

size

public int size()

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

指定者：

介面 Collection<E> 中的 size

指定者：

介面 Deque<E> 中的 size

指定者：

類別 AbstractCollection<E> 中的 size

返回：

此雙端佇列中的元素數

isEmpty

public boolean isEmpty()

如果此雙端佇列未包含任何元素，則返回 true。

指定者：

介面 Collection<E> 中的 isEmpty

覆寫：

類別 AbstractCollection<E> 中的 isEmpty

返回：

如果此雙端佇列未包含任何元素，則返回 true

iterator

public Iterator<E> iterator()

返回在此雙端佇列的元素上進行迭代的迭代器。元素將按從第一個（頭）到最後一個（尾）的順序進行排序。這與元素出列（通過連續調用 remove()）或彈出（通過連續調用 pop()）的順序相同。

指定者：

介面 Iterable<E> 中的 iterator

指定者：

介面 Collection<E> 中的 iterator

指定者：

介面 Deque<E> 中的 iterator

指定者：

類別 AbstractCollection<E> 中的 iterator

返回：

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

descendingIterator

public Iterator<E> descendingIterator()

從介面 Deque 複製的描述

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

指定者：

介面 Deque<E> 中的 descendingIterator

返回：

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

contains

public boolean contains(Object o)

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

指定者：

介面 Collection<E> 中的 contains

指定者：

介面 Deque<E> 中的 contains

覆寫：

類別 AbstractCollection<E> 中的 contains

參數：

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

返回：

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

remove

public boolean remove(Object o)

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

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

指定者：

介面 Collection<E> 中的 remove

指定者：

介面 Deque<E> 中的 remove

覆寫：

類別 AbstractCollection<E> 中的 remove

參數：

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

返回：

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

clear

public void clear()

從此雙端佇列中移除所有元素。在此調用返回之後，該雙端佇列將為空。

指定者：

介面 Collection<E> 中的 clear

覆寫：

類別 AbstractCollection<E> 中的 clear

toArray

public Object[] toArray()

返回一個以恰當順序包含此雙端佇列所有元素的陣列（從第一個元素到最後一個元素）。

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

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

指定者：

介面 Collection<E> 中的 toArray

覆寫：

類別 AbstractCollection<E> 中的 toArray

返回：

包含此雙端佇列中所有元素的陣列。

toArray

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

返回一個以恰當順序包含此雙端佇列所有元素的陣列（從第一個元素到最後一個元素）；返回陣列的運行時型別是指定陣列的運行時型別。如果指定的陣列能容納雙端佇列，則將它返回此處。否則，將分派一個具有指定陣列的運行時型別和此雙端佇列大小的新陣列。

如果指定的陣列能容納此雙端佇列，並有剩餘的空間（即陣列的元素比此雙端佇列多），那麼將陣列中緊接雙端佇列尾部的元素設置為 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 - 要用來存儲雙端佇列元素的陣列（如果該陣列足夠大）；否則，將為此分派一個具有相同運行時型別的新陣列

返回：

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

拋出：

ArrayStoreException - 如果指定陣列的運行時型別不是此雙端佇列每個元素的運行時型別的父級類別型

NullPointerException - 如果指定的陣列為 null

clone

public ArrayDeque<E> clone()

返回此雙端佇列的副本。

覆寫：

類別 Object 中的 clone

返回：

此雙端佇列的副本

另請參見：

Cloneable