1、接口定義

支持在頭尾兩端插入和移除元素的線性集合（雙端隊(duì)列：Double Ended Queue，Deque，讀音：英[dek]｜美[d?k] ）。大多數(shù) Deque 實(shí)現(xiàn)對于它們可能包含的元素數(shù)量沒有固定的限制，不過這個接口對容量設(shè)限以及沒有固定容量限制的那些 Deque 實(shí)現(xiàn)都支持。

該接口定義了訪問 Deque 兩端元素的方法，方法被提供用于插入、提取和檢索操作。這些操作方法都以兩種形式存在：一種在操作失敗時拋出異常，另一種是返回一個特殊值（根據(jù)操作的不同，可以是 null 或 false）。后一種形式的插入操作是專門為使用容量設(shè)限的 Deque 實(shí)現(xiàn)而設(shè)計(jì)的；在大多數(shù)實(shí)現(xiàn)中，插入操作不會失敗。

這個接口繼承了 Queue 接口。當(dāng)使用 Deque 作為 Queue 隊(duì)列時，會產(chǎn)生 FIFO （先進(jìn)先出）行為：元素被添加到 Deque 的尾部，然后從頭部移除。從 Queue 接口繼承的方法精確地等同于 Deque 方法，如下表所示：

Deque 也可用作 LIFO（后進(jìn)先出） Stack 堆棧。應(yīng)該優(yōu)先使用這個接口，而不是歷史遺留的 java.util.Stack 類。當(dāng)一個 Deque 被用作堆棧時，元素從該 Deque 的頭部被壓入和彈出。Stack 方法與 Deque 方法完全等價，如下表所示：

請注意，當(dāng) Deque 被用作 Queue 隊(duì)列或 Stack 堆棧時，peek() 方法同樣有效；在這兩種情況下，元素都是從 Deque 的頭部提取的。

這個接口還提供了兩個方法來移除內(nèi)部元素，removeFirstOccurrence() 和 removeLastOccurrence()。

與 java.util.List 接口不同，該接口不支持對元素的索引訪問。

雖然 Deque 實(shí)現(xiàn)并不嚴(yán)格要求禁止插入 null 元素，但強(qiáng)烈建議這樣做。任何允許 null 元素的 Deque 實(shí)現(xiàn)的使用者都強(qiáng)烈建議不要利用插入 null 元素的能力。這是因?yàn)?null 會被各種方法用作特殊的返回值，以表明 Deque 為空。

Deque 實(shí)現(xiàn)通常不定義 equals() 和 hashCode() 的基于元素版本的方法，而是從類 Object 繼承基于標(biāo)識版本的方法。

java.util.Deque 繼承于 java.util.Queue 接口，接口繼承關(guān)系如下圖所示：

deque

2、方法聲明

1）void addFirst(E e);

• 在不違反容量限制的情況下立即將指定的元素插入到該 Deque 的頭部中，當(dāng)使用容量設(shè)限的 Deque 時，通常最好使用 offerFirst() 方法；

• 如果此時由于容量限制（沒有可用空間）而不能添加元素，則拋出 java.lang.IllegalStateException；

• 如果指定元素的類阻止將其添加到此隊(duì)列中，則拋出 java.lang.ClassCastException；

• 如果指定的元素為 null 且該隊(duì)列不允許 null 元素，則拋出 java.lang.NullPointerException；

• 如果此元素的某些屬性阻止將其添加到此隊(duì)列中，則拋出 java.lang.IllegalArgumentException。

2）void addLast(E e);

• 在不違反容量限制的情況下立即將指定的元素插入到該 Deque 的尾部中，當(dāng)使用容量設(shè)限的 Deque 時，通常最好使用 offerLast() 方法；

• 如果此時由于容量限制（沒有可用空間）而不能添加元素，則拋出 java.lang.IllegalStateException；

• 如果指定元素的類阻止將其添加到此隊(duì)列中，則拋出 java.lang.ClassCastException；

• 如果指定的元素為 null 且該隊(duì)列不允許 null 元素，則拋出 java.lang.NullPointerException；

• 如果此元素的某些屬性阻止將其添加到此隊(duì)列中，則拋出 java.lang.IllegalArgumentException。

3）boolean offerFirst(E e);

• 將指定的元素插入到 Deque 的頭部，除非它違反容量限制，成功時返回 true，否則返回 false。當(dāng)使用容量設(shè)限的隊(duì)列時，這個方法通常比 addFirst() 更適合使用，因?yàn)樵诓荒芴砑釉貢r，addFirst() 方法只能拋出異常；

• 如果指定元素的類阻止將其添加到此隊(duì)列中，則拋出 java.lang.ClassCastException；

• 如果指定的元素為 null 且該隊(duì)列不允許 null 元素，則拋出 java.lang.NullPointerException；

• 如果此元素的某些屬性阻止將其添加到此隊(duì)列中，則拋出 java.lang.IllegalArgumentException。

4）boolean offerLast(E e);

• 將指定的元素插入到 Deque 的尾部，除非它違反容量限制，成功時返回 true，否則返回 false。當(dāng)使用容量設(shè)限的隊(duì)列時，這個方法通常比 addLast() 更適合使用，因?yàn)樵诓荒芴砑釉貢r，addLast() 方法只能拋出異常；

• 如果指定元素的類阻止將其添加到此隊(duì)列中，則拋出 java.lang.ClassCastException；

• 如果指定的元素為 null 且該隊(duì)列不允許 null 元素，則拋出 java.lang.NullPointerException；

• 如果此元素的某些屬性阻止將其添加到此隊(duì)列中，則拋出 java.lang.IllegalArgumentException。

5）E removeFirst();

• 檢索并移除該 Deque 的第一個元素（頭部元素）。此方法與 pollFirst() 的不同之處在于：當(dāng)該 Deque 為空時，則拋出異常；

• 如果該 Deque 為空，則拋出 java.util.NoSuchElementException。

6）E removeLast();

• 檢索并移除該 Deque 的最后一個元素（尾部元素）。此方法與 pollLast() 的不同之處在于：當(dāng)該 Deque 為空時，則拋出異常；

• 如果該 Deque 為空，則拋出 java.util.NoSuchElementException。

7）E pollFirst();

• 檢索并移除該 Deque 的第一個元素（頭部元素），如果該 Deque 為空，則返回 null。

8）E pollLast();

• 檢索并移除該 Deque 的最后一個元素（尾部元素），如果該 Deque 為空，則返回 null。

9）E getFirst();

• 檢索（但并不移除）該 Deque 的第一個元素（頭部元素）。此方法與 peekFirst() 的不同之處在于：當(dāng)該 Deque 為空時，則拋出異常；

• 如果該 Deque 為空，則拋出 java.util.NoSuchElementException。

10）E getLast();

• 檢索（但并不移除）該 Deque 的最后一個元素（尾部元素）。此方法與 peekLast() 的不同之處在于：當(dāng)該 Deque 為空時，則拋出異常；

• 如果該 Deque 為空，則拋出 java.util.NoSuchElementException。

11）E peekFirst();

• 檢索（但并不移除）該 Deque 的第一個元素（頭部元素），如果該 Deque 為空，則返回 null。

12）E peekLast();

• 檢索（但并不移除）該 Deque 的最后一個元素（尾部元素），如果該 Deque 為空，則返回 null。

13）boolean removeFirstOccurrence(Object o);

• 從 Deque 中移除指定元素的第一個匹配項(xiàng)。如果該 Deque 中不包含該元素，則它不會有所改變。更正式地說，即移除第一個滿足 (o==null ? e==null : o.equals(e)) 表達(dá)式的元素 e（如果存在這樣的元素的話）。如果該 Deque 包含指定的元素則移除它并返回 true；

• 如果指定元素的類型與 Deque 不兼容，則拋出 java.lang.ClassCastException（可選）；

• 如果指定的元素是 null，而這個 Deque 是不允許 null 元素的，則拋出 java.lang.NullPointerException（可選）。

注：“可選”指具體的 Deque 實(shí)現(xiàn)可根據(jù)自己的實(shí)現(xiàn)目的而選擇合適的策略，或返回此異常，或返回成功。

14）boolean removeLastOccurrence(Object o);

• 從 Deque 中移除指定元素的最后一個匹配項(xiàng)。如果該 Deque 中不包含該元素，則它不會有所改變。更正式地說，即移除最后一個滿足 (o==null ? e==null : o.equals(e)) 表達(dá)式的元素 e（如果存在這樣的元素的話）。如果該 Deque 包含指定的元素則移除它并返回 true；

• 如果指定元素的類型與 Deque 不兼容，則拋出 java.lang.ClassCastException（可選）；

• 如果指定的元素是 null，而這個 Deque 是不允許 null 元素的，則拋出 java.lang.NullPointerException（可選）。

— 以下為 Queue 隊(duì)列方法 —

15）boolean add(E e);

• 如果可以在不違反容量限制的情況下立即將指定的元素插入到該 Deque 所表示的 Queue 隊(duì)列中（換句話說，插入到該 Deque 的尾部），則在插入成功時返回 true（如 Collection.add() 所指定的），當(dāng)使用容量設(shè)限的 Deque 時，通常最好使用 offer() 方法。此方法與 addLast() 方法等效；

• 如果此時由于容量限制（沒有可用空間）而不能添加元素，則拋出 java.lang.IllegalStateException；

• 如果指定元素的類阻止將其添加到此隊(duì)列中，則拋出 java.lang.ClassCastException；

• 如果指定的元素為 null 且該隊(duì)列不允許 null 元素，則拋出 java.lang.NullPointerException；

• 如果此元素的某些屬性阻止將其添加到此隊(duì)列中，則拋出 java.lang.IllegalArgumentException。

16）boolean offer(E e);

• 如果可以在不違反容量限制的情況下立即將指定的元素插入到該 Deque 所表示的 Queue 隊(duì)列中（換句話說，插入到該 Deque 的尾部），則在插入成功時返回 true，否則返回 false，當(dāng)使用容量設(shè)限的 Deque 時，這個方法通常比 add() 更適合使用，因?yàn)樵谝蛉萘肯拗疲]有可用空間）而不能添加元素時，add() 方法只能拋出異常。此方法與 offerLast() 方法等效；

• 如果指定元素的類阻止將其添加到此隊(duì)列中，則拋出 java.lang.ClassCastException；

• 如果指定的元素為 null 且該隊(duì)列不允許 null 元素，則拋出 java.lang.NullPointerException；

• 如果此元素的某些屬性阻止將其添加到此隊(duì)列中，則拋出 java.lang.IllegalArgumentException。

17）E remove();

• 檢索并移除此 Deque 所表示的 Queue 隊(duì)列的頭部元素（換句話說，移除該 Deque 的第一個元素），此方法與 poll() 方法的不同之處在于：如果隊(duì)列為空，則拋出異常。此方法與 removeFirst() 方法等效；

• 如果隊(duì)列為空，則拋出 java.util.NoSuchElementException。

18）E poll();

• 檢索并移除此 Deque 所表示的 Queue 隊(duì)列的頭部元素（換句話說，移除該 Deque 的第一個元素），如果隊(duì)列為空，返回 null。此方法與 pollFirst() 方法等效。

19）E element();

• 檢索（但并不移除）此 Deque 所表示的 Queue 隊(duì)列的頭部元素（換句話說，檢索該 Deque 的第一個元素），此方法與 peek() 方法的不同之處在于：如果隊(duì)列為空，則拋出異常。此方法與 getFirst() 方法等效；

• 如果隊(duì)列為空，則拋出 java.util.NoSuchElementException。

20）E peek();

• 檢索（但并不移除）此 Deque 所表示的 Queue 隊(duì)列的頭部元素（換句話說，檢索該 Deque 的第一個元素），如果隊(duì)列為空，返回 null。此方法與 peekFirst() 方法等效。

— 以下為 Stack 堆棧方法 —

21）void push(E e);

• 在不違反容量限制的情況下立即將一個元素壓入到該 Deque 所表示的 Stack 堆棧中（換句話說，壓入到該 Deque 的頭部）。此方法與 addFirst() 方法等效；

• 如果此時由于容量限制（沒有可用空間）而不能添加元素，則拋出 java.lang.IllegalStateException；

• 如果指定元素的類阻止將其添加到此堆棧中，則拋出 java.lang.ClassCastException；

• 如果指定的元素為 null 且該堆棧不允許 null 元素，則拋出 java.lang.NullPointerException；

• 如果此元素的某些屬性阻止將其添加到此堆棧中，則拋出 java.lang.IllegalArgumentException。

22）E pop();

• 從這個 Deque 所表示的 Stack 堆棧中彈出一個元素。換句話說，移除并返回該 Deque 的第一個元素。此方法與 removeFirst() 方法等效；

• 如果堆棧為空，則拋出 java.util.NoSuchElementException。

— 以下為 Collection 集合方法 —

23）boolean remove(Object o);

• 從 Deque 中移除指定元素的第一個匹配項(xiàng)。如果該 Deque 中不包含該元素，則它不會有所改變。更正式地說，即移除第一個滿足 (o==null ? e==null : o.equals(e)) 表達(dá)式的元素 e（如果存在這樣的元素的話）。如果該 Deque 包含指定的元素則移除它并返回 true。此方法與 removeFirstOccurrence(Object o) 方法等效；

• 如果指定元素的類型與 Deque 不兼容，則拋出 java.lang.ClassCastException（可選）；

• 如果指定的元素是 null，而這個 Deque 是不允許 null 元素的，則拋出 java.lang.NullPointerException（可選）。

24）boolean contains(Object o);

• 如果 Deque 包含指定的元素時返回 true。更正式地說，當(dāng)且僅當(dāng)這個 Deque 至少包含一個滿足 (o==null ? e==null : o.equals(e)) 表達(dá)式的元素 e 時返回 true；

• 如果指定元素的類型與 Deque 不兼容，則拋出 java.lang.ClassCastException（可選）；

• 如果指定的元素是 null，而這個 Deque 是不允許 null 元素的，則拋出 java.lang.NullPointerException（可選）。

25）public int size();

• 返回 Deque 中包含的元素的數(shù)量。

26）Iterator<E> iterator();

• 按照順序返回 Deque 中所有元素的迭代器，元素將按從頭到尾的順序返回。

27）Iterator<E> descendingIterator();

• 以反向順序返回該 Deque 中所有元素的迭代器，元素將按從尾到頭的順序返回。