类型参数:: E - 此双端队列中保存的元素类型

所有超接口:: Collection<E>, Iterable<E>, Queue<E>, SequencedCollection<E>

所有已知子接口:: BlockingDeque<E>

所有已知实现类:: ArrayDeque, ConcurrentLinkedDeque, LinkedBlockingDeque, LinkedList

public interface Deque<E> extends Queue<E>, SequencedCollection<E>

支持在两端插入和移除元素的线性集合。名称 deque 是 "double ended queue" 的缩写，通常发音为 "deck"。大多数 Deque 实现对它们所包含的元素数量没有固定限制，但此接口支持容量受限的双端队列以及没有固定大小限制的双端队列。

此接口定义了访问双端队列两端元素的方法。提供了插入、移除和检查元素的方法。每个方法都有两种形式：一种在操作失败时抛出异常，另一种返回一个特殊值（根据操作不同，可能是 null 或 false）。后一种插入操作形式专为容量受限的 Deque 实现而设计；在大多数实现中，插入操作不会失败。

上述十二种方法在下表中进行了总结：

双端队列方法摘要
	抛出异常	特殊值	抛出异常	特殊值
	第一个元素（头部）		最后一个元素（尾部）
插入	`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()`	`getFirst()`

请注意，当双端队列用作队列或堆栈时，peek 方法同样有效；在任一情况下，元素都是从双端队列的开头获取的。

此接口提供两种方法来移除内部元素，removeFirstOccurrence 和 removeLastOccurrence。

与 List 接口不同，此接口不支持对元素的索引访问。

虽然 Deque 实现不严格要求禁止插入空元素，但强烈建议这样做。强烈建议允许插入空元素的任何 Deque 实现的用户不要利用插入空元素的能力。这是因为 null 被各种方法用作特殊返回值，表示双端队列为空。

Deque 实现通常不定义基于元素的 equals 和 hashCode 方法，而是从 Object 类继承基于标识的版本。

此接口是 Java集合框架的成员。

自 JDK 版本:: 1.6

Method Summary

Modifier and Type

Method

Description

boolean

add(E e)

如果可以立即在不违反容量限制的情况下将指定元素插入此双端队列所表示的队列（换句话说，在此双端队列的尾部），则返回 true 表示成功，并在当前没有可用空间时抛出 IllegalStateException。

boolean

addAll(Collection<? extends E> c)

将指定集合中的所有元素按照它们由集合的迭代器返回的顺序，依次添加到此双端队列的末尾，就好像对每个元素调用 addLast(E) 一样。

void

addFirst(E e)

如果可以立即在不违反容量限制的情况下将指定元素插入此双端队列的前面，则抛出 IllegalStateException，表示当前没有可用空间。

void

addLast(E e)

如果可以立即在不违反容量限制的情况下将指定元素插入此双端队列的末尾，则抛出 IllegalStateException，表示当前没有可用空间。

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)

如果可以立即在不违反容量限制的情况下将指定元素推送到此双端队列表示的堆栈（换句话说，在此双端队列的头部），则抛出 IllegalStateException，表示当前没有可用空间。

E

remove()

从此双端队列中检索并移除队列的头部（换句话说，此双端队列的第一个元素）。

boolean

remove(Object o)

从此双端队列中移除指定元素的第一个出现。

E

removeFirst()

检索并移除此双端队列的第一个元素。

boolean

removeFirstOccurrence(Object o)

从此双端队列中移除指定元素的第一个出现。

E

removeLast()

检索并移除此双端队列的最后一个元素。

boolean

removeLastOccurrence(Object o)

从此双端队列中移除指定元素的最后一个出现。

default Deque<E>

reversed()

返回此集合的逆序视图。

int

size()

返回此双端队列中的元素数量。

Methods declared in interface java.util.Collection
clear, containsAll, equals, hashCode, isEmpty, parallelStream, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray, toArray

Methods declared in interface java.lang.Iterable
forEach

Method Details
- addFirst
  
  void addFirst(E e)
  
  如果可以立即在不违反容量限制的情况下将指定元素插入此双端队列的前面，则将其插入，如果当前没有可用空间，则抛出IllegalStateException。在使用容量受限的双端队列时，通常最好使用方法offerFirst(E)。
  
  指定者：
  
  addFirst 在接口 SequencedCollection<E>
  
  参数：
  
  e - 要添加的元素
  
  抛出：
  
  IllegalStateException - 如果由于容量限制而当前无法添加元素
  
  ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
  
  NullPointerException - 如果指定元素为null且此双端队列不允许空元素
  
  IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中
- addLast
  
  void addLast(E e)
  
  如果可以立即在不违反容量限制的情况下将指定元素插入此双端队列的末尾，则将其插入，如果当前没有可用空间，则抛出IllegalStateException。在使用容量受限的双端队列时，通常最好使用方法offerLast(E)。
  此方法等效于add(E)。
  
  指定者：
  
  addLast 在接口 SequencedCollection<E>
  
  参数：
  
  e - 要添加的元素
  
  抛出：
  
  IllegalStateException - 如果由于容量限制而当前无法添加元素
  
  ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
  
  NullPointerException - 如果指定元素为null且此双端队列不允许空元素
  
  IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中
- offerFirst
  
  boolean offerFirst(E e)
  
  除非违反容量限制，否则将指定元素插入此双端队列的前面。在使用容量受限的双端队列时，通常最好使用addFirst(E)方法，该方法只能通过抛出异常来插入元素失败。
  
  参数：
  
  e - 要添加的元素
  
  返回：
  
  true 如果元素已添加到此双端队列，否则为false
  
  抛出：
  
  ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
  
  NullPointerException - 如果指定元素为null且此双端队列不允许空元素
  
  IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中
- offerLast
  
  boolean offerLast(E e)
  
  除非违反容量限制，否则将指定元素插入此双端队列的末尾。在使用容量受限的双端队列时，通常最好使用addLast(E)方法，该方法只能通过抛出异常来插入元素失败。
  
  参数：
  
  e - 要添加的元素
  
  返回：
  
  true 如果元素已添加到此双端队列，否则为false
  
  抛出：
  
  ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
  
  NullPointerException - 如果指定元素为null且此双端队列不允许空元素
  
  IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中
- removeFirst
  
  E removeFirst()
  
  检索并移除此双端队列的第一个元素。此方法与pollFirst的区别仅在于，如果此双端队列为空，则会抛出异常。
  
  指定者：
  
  removeFirst 在接口 SequencedCollection<E>
  
  返回：
  
  此双端队列的头部
  
  抛出：
  
  NoSuchElementException - 如果此双端队列为空
- removeLast
  
  E removeLast()
  
  检索并移除此双端队列的最后一个元素。此方法与pollLast的区别仅在于，如果此双端队列为空，则会抛出异常。
  
  指定者：
  
  removeLast 在接口 SequencedCollection<E>
  
  返回：
  
  此双端队列的尾部
  
  抛出：
  
  NoSuchElementException - 如果此双端队列为空
- pollFirst
  
  E pollFirst()
  
  检索并移除此双端队列的第一个元素，如果此双端队列为空，则返回null。
  
  返回：
  
  此双端队列的头部，如果此双端队列为空，则为null
- pollLast
  
  E pollLast()
  
  检索并移除此双端队列的最后一个元素，如果此双端队列为空，则返回null。
  
  返回：
  
  此双端队列的尾部，如果此双端队列为空，则为null
- getFirst
  
  E getFirst()
  
  检索但不移除此双端队列的第一个元素。此方法与peekFirst的区别仅在于，如果此双端队列为空，则会抛出异常。
  
  指定者：
  
  getFirst 在接口 SequencedCollection<E>
  
  返回：
  
  此双端队列的头部
  
  抛出：
  
  NoSuchElementException - 如果此双端队列为空
- getLast
  
  E getLast()
  
  检索但不移除此双端队列的最后一个元素。此方法与peekLast的区别仅在于，如果此双端队列为空，则会抛出异常。
  
  指定者：
  
  getLast 在接口 SequencedCollection<E>
  
  返回：
  
  此双端队列的尾部
  
  抛出：
  
  NoSuchElementException - 如果此双端队列为空
- peekFirst
  
  E peekFirst()
  
  检索但不移除此双端队列的第一个元素，如果此双端队列为空，则返回null。
  
  返回：
  
  此双端队列的头部，如果此双端队列为空，则为null
- peekLast
  
  E peekLast()
  
  检索但不移除此双端队列的最后一个元素，如果此双端队列为空，则返回null。
  
  返回：
  
  此双端队列的尾部，如果此双端队列为空，则为null
- removeFirstOccurrence
  
  boolean removeFirstOccurrence(Object o)
  
  从此双端队列中移除指定元素的第一个出现。如果双端队列不包含该元素，则保持不变。更正式地说，移除第一个元素e，使得Objects.equals(o, e)（如果存在这样的元素）。如果此双端队列包含指定元素（或等效地，如果此双端队列由于调用而发生更改），则返回true。
  
  参数:
  
  o - 如果存在，则从此双端队列中移除的元素
  
  返回:
  
  true - 如果作为此调用的结果移除了一个元素
  
  抛出:
  
  ClassCastException - 如果指定元素的类与此双端队列不兼容（可选）
  
  NullPointerException - 如果指定元素为null且此双端队列不允许null元素（可选）
- removeLastOccurrence
  
  boolean removeLastOccurrence(Object o)
  
  从此双端队列中移除指定元素的最后一个出现。如果双端队列不包含该元素，则保持不变。更正式地说，移除最后一个元素e，使得Objects.equals(o, e)（如果存在这样的元素）。如果此双端队列包含指定元素，则返回true（或等效地，如果此双端队列由于调用而更改）。
  
  参数:
  
  o - 如果存在，则从此双端队列中移除的元素
  
  返回:
  
  true - 如果作为此调用的结果移除了一个元素
  
  抛出:
  
  ClassCastException - 如果指定元素的类与此双端队列不兼容（可选）
  
  NullPointerException - 如果指定元素为null且此双端队列不允许null元素（可选）
- add
  
  boolean add(E e)
  
  将指定元素插入到此双端队列表示的队列（换句话说，在此双端队列的尾部），如果可以立即这样做而不违反容量限制，则返回true以表示成功，并在当前没有可用空间时抛出IllegalStateException。在使用容量受限的双端队列时，通常最好单独调用offer。
  此方法等效于addLast(E)。
  
  参数:
  
  e - 要添加的元素
  
  返回:
  
  true（由Collection.add(E)指定）
  
  抛出:
  
  IllegalStateException - 如果由于容量限制而无法此时添加元素
  
  ClassCastException - 如果指定元素的类阻止将其添加到此双端队列
  
  NullPointerException - 如果指定元素为null且此双端队列不允许null元素
  
  IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列
- offer
  
  boolean offer(E e)
  
  如果可以立即在不违反容量限制的情况下将指定集合中的所有元素添加到此双端队列的末尾，就像通过调用集合的迭代器返回的顺序依次调用addLast(E)一样。
  在使用容量受限的双端队列时，通常最好分别对每个元素调用offer。
  
  在尝试添加元素时遇到异常时，当抛出相关异常时，可能只有一些元素已成功添加。
  
  参数:
  
  e - 要添加的元素
  
  返回:
  
  true - 如果此调用的结果将元素添加到此双端队列，否则false
  
  抛出:
  
  ClassCastException - 如果指定元素的类阻止将其添加到此双端队列
  
  NullPointerException - 如果指定元素为null且此双端队列不允许null元素
  
  IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列
- remove
  
  E remove()
  
  检索并移除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素）。此方法与poll()的区别仅在于，如果此双端队列为空，则会抛出异常。
  此方法等效于removeFirst()。
  
  返回:
  
  由此双端队列表示的队列的头部
  
  抛出:
  
  NoSuchElementException - 如果此双端队列为空
- poll
  
  E poll()
  
  检索并移除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），如果此双端队列为空，则返回null。
  此方法等效于pollFirst()。
  
  返回:
  
  此双端队列的第一个元素，如果此双端队列为空，则返回null
- element
  
  E element()
  
  检索但不移除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素）。此方法与peek的区别仅在于，如果此双端队列为空，则会抛出异常。
  此方法等效于getFirst()。
  
  返回:
  
  由此双端队列表示的队列的头部
  
  抛出:
  
  NoSuchElementException - 如果此双端队列为空
- peek
  
  E peek()
  
  检索但不移除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），如果此双端队列为空，则返回null。
  此方法等效于peekFirst()。
  
  返回:
  
  由此双端队列表示的队列的头部，如果此双端队列为空，则返回null
- addAll
  
  boolean addAll(Collection<? extends E> c)
  
  将指定集合中的所有元素按照它们由集合的迭代器返回的顺序依次添加到此双端队列的末尾，就像通过对每个元素调用addLast(E)一样。
  在使用容量受限的双端队列时，通常最好分别对每个元素调用offer。
  
  在尝试添加元素时遇到异常时，当抛出相关异常时，可能只有一些元素已成功添加。
  
  参数:
  
  c - 要插入到此双端队列中的元素
  
  返回:
  
  true - 如果此调用的结果导致此双端队列更改
  
  抛出:
  
  IllegalStateException - 如果由于插入限制而无法此时添加所有元素
  
  ClassCastException - 如果指定集合的某个元素的类阻止将其添加到此双端队列
  
  NullPointerException - 如果指定集合包含null元素且此双端队列不允许null元素，或者指定集合为null
  
  IllegalArgumentException - 如果指定集合的某个元素的某些属性阻止将其添加到此双端队列
- push
  
  void push(E e)
  
  如果可以立即在不违反容量限制的情况下将元素推送到此双端队列表示的堆栈（换句话说，在此双端队列的头部），则抛出IllegalStateException，表示当前没有可用空间。
  此方法等效于addFirst(E)。
  
  参数:
  
  e - 要推送的元素
  
  抛出:
  
  IllegalStateException - 如果由于容量限制而无法在此时添加元素
  
  ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
  
  NullPointerException - 如果指定元素为null且此双端队列不允许null元素
  
  IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中
- pop
  
  E pop()
  
  从由此双端队列表示的堆栈中弹出一个元素。换句话说，移除并返回此双端队列的第一个元素。
  此方法等效于removeFirst()。
  
  返回:
  
  此双端队列前端的元素（即由此双端队列表示的堆栈的顶部）
  
  抛出:
  
  NoSuchElementException - 如果此双端队列为空
- remove
  
  boolean remove(Object o)
  
  从此双端队列中删除指定元素的第一个出现。如果双端队列不包含该元素，则保持不变。更正式地说，删除第一个元素e，使得Objects.equals(o, e)（如果存在这样的元素）。如果此双端队列包含指定元素（或等效地，如果此双端队列由于调用而更改），则返回true。
  此方法等效于removeFirstOccurrence(Object)。
  
  指定者:
  
  remove 在接口 Collection<E>
  
  参数:
  
  o - 如果存在，则从此双端队列中删除的元素
  
  返回:
  
  如果通过此调用删除了一个元素，则返回true
  
  抛出:
  
  ClassCastException - 如果指定元素的类别与此双端队列不兼容（可选）
  
  NullPointerException - 如果指定元素为null且此双端队列不允许null元素（可选）
- contains
  
  boolean contains(Object o)
  
  如果此双端队列包含指定元素，则返回true。更正式地说，如果此双端队列包含至少一个元素e，使得Objects.equals(o, e)，则返回true。
  
  指定者:
  
  contains 在接口 Collection<E>
  
  参数:
  
  o - 要测试其在此双端队列中存在性的元素
  
  返回:
  
  如果此双端队列包含指定元素，则返回true
  
  抛出:
  
  ClassCastException - 如果指定元素的类别与此双端队列不兼容（可选）
  
  NullPointerException - 如果指定元素为null且此双端队列不允许null元素（可选）
- size
  
  int size()
  
  返回此双端队列中的元素数量。
  
  指定者:
  
  size 在接口 Collection<E>
  
  返回:
  
  此双端队列中的元素数量
- iterator
  
  Iterator<E> iterator()
  
  返回此双端队列中元素的迭代器，按正确顺序返回元素。元素将按从第一个（头部）到最后一个（尾部）的顺序返回。
  
  指定者:
  
  iterator 在接口 Collection<E>
  
  指定者:
  
  iterator 在接口 Iterable<E>
  
  返回:
  
  按正确顺序返回此双端队列中元素的迭代器
- descendingIterator
  
  Iterator<E> descendingIterator()
  
  返回此双端队列中元素的反向顺序迭代器。元素将按从最后一个（尾部）到第一个（头部）的顺序返回。
  
  返回:
  
  按反向顺序返回此双端队列中元素的迭代器
- reversed
  
  default Deque<E> reversed()
  
  返回此集合的反向排序视图。返回视图中元素的遭遇顺序与此集合中元素的遭遇顺序相反。反向排序会影响所有对顺序敏感的操作，包括对返回视图的集合的操作。如果集合实现允许对此视图进行修改，则修改会“写入”到基础集合。对基础集合的更改可能会或可能不会在此反转视图中可见，这取决于实现。
  
  指定者:
  
  reversed 在接口 SequencedCollection<E>
  
  实现要求:
  
  此接口中的实现返回一个反向排序的双端队列视图。视图的reversed()方法返回对此双端队列的引用。视图上的其他操作通过调用此双端队列上的公共方法来实现。调用视图上的调用与调用此双端队列上的调用之间的确切关系未指定。但是，对于顺序敏感的操作，通常会委托给具有相反方向的适当方法。例如，在视图上调用getFirst会导致在此双端队列上调用getLast。
  
  返回:
  
  作为Deque的此集合的反向排序视图
  
  自:
  
  21

Interface Deque<E>

Method Summary

Methods declared in interface java.util.Collection

Methods declared in interface java.lang.Iterable

Method Details

addFirst

addLast

offerFirst

offerLast

removeFirst

removeLast

pollFirst

pollLast

getFirst

getLast

peekFirst

peekLast

removeFirstOccurrence

removeLastOccurrence

add

offer

remove

poll

element

peek

addAll

push

pop

remove

contains

size

iterator

descendingIterator

reversed