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 类。在将双端队列用作堆栈时，元素被推入双端队列的开头并从双端队列开头弹出。堆栈方法完全等效于 Deque 方法，如下表所示：

堆栈方法	等效 Deque 方法
push(e)	addFirst(e)
pop()	removeFirst()
peek()	peekFirst()

注意，在将双端队列用作队列或堆栈时，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() 从此双端队列所表示的堆栈中弹出一个元素。
void	push(E e) 将一个元素推入此双端队列所表示的堆栈（换句话说，此双端队列的头部），如果可以直接这样做而不违反容量限制的话；如果成功，则返回 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)

将一个元素推入此双端队列所表示的堆栈（换句话说，此双端队列的头部），如果可以直接这样做而不违反容量限制的话；如果成功，则返回 true，如果当前没有可用空间，则抛出 IllegalStateException。

此方法等效于 addFirst(E)。

参数：

e - 要推入的元素

抛出：

IllegalStateException - 如果此时由于容量限制而无法添加元素

ClassCastException - 如果指定元素的类不允许将它添加此双端队列

NullPointerException - 如果指定元素为 null，并且此双端队列不允许 null 元素

IllegalArgumentException - 如果指定元素的某些属性不允许将它添加到此双端队列

pop

E pop()

从此双端队列所表示的堆栈中弹出一个元素。换句话说，移除并返回此双端队列第一个元素。

此方法等效于 removeFirst()。

返回：

此双端队列开头的元素（它是此双端队列所表示的堆栈的顶部）

抛出：

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()

返回以逆向顺序在此双端队列的元素上进行迭代的迭代器。元素将按从最后一个（尾部）到第一个（头部）的顺序返回。

返回：

以逆向顺序在此双端队列中的元素上进行迭代的迭代器