类型参数：: E - 此双端队列中包含的元素类型

所有父级接口：: Collection<E> , Iterable<E> , Queue<E>

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

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

public interface Deque<E> extends Queue <E>

支持两端元素插入和移除的线性集合。名字双端队列是“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 方法的比较
`Queue`方法	等价于`Deque`方法
`add(e)`	`addLast(e)`
`offer(e)`	`offerLast(e)`
`remove()`	`removeFirst()`
`poll()`	`pollFirst()`
`element()`	`getFirst()`
`peek()`	`peekFirst()`

双端队列也可以用作 LIFO（后进先出）堆栈。应优先使用此接口而不是遗留的 Stack 类。当双端队列用作堆栈时，元素从双端队列的开头被压入和弹出。堆栈方法等同于 Deque 方法，如下表所示：

Stack 和 Deque 方法的比较
栈方法	等价于`Deque`方法
`push(e)`	`addFirst(e)`
`pop()`	`removeFirst()`
`peek()`	`getFirst()`

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

该接口提供了两种移除内部元素的方法，removeFirstOccurrence 和 removeLastOccurrence 。

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

虽然没有严格要求 Deque 实现禁止插入空元素，但强烈建议它们这样做。强烈鼓励任何允许空元素的 Deque 实现的用户not利用插入空值的能力。之所以如此，是因为 null 被各种方法用作特殊的返回值，以指示双端队列为空。

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

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

自从：: 1.6

方法总结

修饰符和类型

方法

描述

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)

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

int

size()

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

在接口 java.util.Collection 中声明的方法
clear, containsAll, equals, hashCode, isEmpty, parallelStream, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray, toArray

在接口 java.lang.Iterable 中声明的方法
forEach

方法详情
- addFirst
  
  void addFirst(E e)
  
  如果可以在不违反容量限制的情况下立即插入指定元素，则将指定元素插入此双端队列的前面，如果当前没有可用空间，则抛出 IllegalStateException。使用容量受限的双端队列时，通常最好使用方法 offerFirst(E) 。
  
  参数：
  
  e - 要添加的元素
  
  抛出：
  
  IllegalStateException - 如果由于容量限制此时无法添加元素
  
  ClassCastException - 如果指定元素的类阻止将其添加到此双端队列
  
  NullPointerException - 如果指定元素为空且此双端队列不允许空元素
  
  IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列
- addLast
  
  void addLast(E e)
  
  如果可以在不违反容量限制的情况下立即插入指定元素，则在此双端队列的末尾插入指定元素，如果当前没有可用空间，则抛出 IllegalStateException。使用容量受限的双端队列时，通常最好使用方法 offerLast(E) 。
  此方法等效于 add(E) 。
  
  参数：
  
  e - 要添加的元素
  
  抛出：
  
  IllegalStateException - 如果由于容量限制此时无法添加元素
  
  ClassCastException - 如果指定元素的类阻止将其添加到此双端队列
  
  NullPointerException - 如果指定元素为空且此双端队列不允许空元素
  
  IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列
- offerFirst
  
  boolean offerFirst(E e)
  
  将指定的元素插入此双端队列的前面，除非它违反容量限制。当使用容量受限的双端队列时，此方法通常优于 addFirst(E) 方法，后者可能仅通过抛出异常来插入元素失败。
  
  参数：
  
  e - 要添加的元素
  
  返回：
  
  true 如果元素被添加到这个双端队列，否则 false
  
  抛出：
  
  ClassCastException - 如果指定元素的类阻止将其添加到此双端队列
  
  NullPointerException - 如果指定元素为空且此双端队列不允许空元素
  
  IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列
- offerLast
  
  boolean offerLast(E e)
  
  除非违反容量限制，否则在此双端队列的末尾插入指定的元素。当使用容量受限的双端队列时，此方法通常优于 addLast(E) 方法，后者可能仅通过抛出异常来插入元素失败。
  
  参数：
  
  e - 要添加的元素
  
  返回：
  
  true 如果元素被添加到这个双端队列，否则 false
  
  抛出：
  
  ClassCastException - 如果指定元素的类阻止将其添加到此双端队列
  
  NullPointerException - 如果指定元素为空且此双端队列不允许空元素
  
  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)
  
  从此双端队列中移除第一次出现的指定元素。如果双端队列不包含该元素，则它不变。更正式地说，删除第一个元素 e 这样 Objects.equals(o, e) （如果存在这样的元素）。如果此双端队列包含指定元素，则返回 true（或者等效地，如果此双端队列因调用而更改）。
  
  参数：
  
  o - 要从此双端队列中删除的元素（如果存在）
  
  返回：
  
  true 如果一个元素作为这个调用的结果被移除
  
  抛出：
  
  ClassCastException - 如果指定元素的类与此双端队列不兼容 (optional)
  
  NullPointerException - 如果指定元素为 null 并且此双端队列不允许 null 元素 (optional)
- removeLastOccurrence
  
  boolean removeLastOccurrence(Object o)
  
  从此双端队列中移除指定元素的最后一次出现。如果双端队列不包含该元素，则它不变。更正式地说，删除最后一个元素 e 这样 Objects.equals(o, e) （如果存在这样的元素）。如果此双端队列包含指定元素，则返回 true（或者等效地，如果此双端队列因调用而更改）。
  
  参数：
  
  o - 要从此双端队列中删除的元素（如果存在）
  
  返回：
  
  true 如果一个元素作为这个调用的结果被移除
  
  抛出：
  
  ClassCastException - 如果指定元素的类与此双端队列不兼容 (optional)
  
  NullPointerException - 如果指定元素为 null 并且此双端队列不允许 null 元素 (optional)
- add
  
  boolean add(E e)
  
  如果可以在不违反容量限制的情况下立即将指定元素插入此双端队列表示的队列（换句话说，在此双端队列的尾部），成功时返回 true，如果当前没有可用空间则抛出 IllegalStateException .使用容量受限的双端队列时，通常最好使用 offer 。
  此方法等效于 addLast(E) 。
  
  指定者：
  
  add 在接口 Collection<E> 中
  
  指定者：
  
  add 在接口 Queue<E> 中
  
  参数：
  
  e - 要添加的元素
  
  返回：
  
  true（由 Collection.add(E) 指定）
  
  抛出：
  
  IllegalStateException - 如果由于容量限制此时无法添加元素
  
  ClassCastException - 如果指定元素的类阻止将其添加到此双端队列
  
  NullPointerException - 如果指定元素为空且此双端队列不允许空元素
  
  IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列
- offer
  
  boolean offer(E e)
  
  如果可以在不违反容量限制的情况下立即将指定元素插入此双端队列表示的队列（换句话说，在此双端队列的尾部），成功时返回 true，如果当前没有可用空间则返回 false。当使用容量受限的双端队列时，此方法通常优于 add(E) 方法，后者可能仅通过抛出异常来插入元素失败。
  此方法等效于 offerLast(E) 。
  
  指定者：
  
  offer 在接口 Queue<E> 中
  
  参数：
  
  e - 要添加的元素
  
  返回：
  
  true 如果元素被添加到这个双端队列，否则 false
  
  抛出：
  
  ClassCastException - 如果指定元素的类阻止将其添加到此双端队列
  
  NullPointerException - 如果指定元素为空且此双端队列不允许空元素
  
  IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列
- remove
  
  E remove()
  
  检索并删除此双端队列所表示的队列的头部（换句话说，此双端队列的第一个元素）。此方法与 poll() 的不同之处仅在于，如果此双端队列为空，它会抛出异常。
  此方法等效于 removeFirst() 。
  
  指定者：
  
  remove 在接口 Queue<E> 中
  
  返回：
  
  此双端队列所代表的队列的头部
  
  抛出：
  
  NoSuchElementException - 如果这个双端队列是空的
- poll
  
  E poll()
  
  检索并删除此双端队列所表示的队列的头部（换句话说，此双端队列的第一个元素），或者如果此双端队列为空，则返回 null。
  此方法等效于 pollFirst() 。
  
  指定者：
  
  poll 在接口 Queue<E> 中
  
  返回：
  
  此双端队列的第一个元素，如果此双端队列为空，则为 null
- element
  
  E element()
  
  检索但不删除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素）。此方法与 peek 的不同之处仅在于，如果此双端队列为空，它会抛出异常。
  此方法等效于 getFirst() 。
  
  指定者：
  
  element 在接口 Queue<E> 中
  
  返回：
  
  此双端队列所代表的队列的头部
  
  抛出：
  
  NoSuchElementException - 如果这个双端队列是空的
- peek
  
  E peek()
  
  检索但不删除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），或者如果此双端队列为空则返回 null。
  此方法等效于 peekFirst() 。
  
  指定者：
  
  peek 在接口 Queue<E> 中
  
  返回：
  
  此双端队列表示的队列的头部，如果此双端队列为空，则为 null
- addAll
  
  boolean addAll(Collection <? extends E > c)
  
  将指定集合中的所有元素添加到此双端队列的末尾，就像对每个元素调用 addLast(E) 一样，按照集合的迭代器返回它们的顺序。
  使用容量受限的双端队列时，通常最好在每个元素上分别调用 offer 。
  
  尝试添加元素时遇到的异常可能会导致在抛出相关异常时仅成功添加了部分元素。
  指定者：
  
  addAll 在接口 Collection<E> 中
  
  参数：
  
  c - 要插入到此双端队列中的元素
  
  返回：
  
  true 如果此双端队列因调用而改变
  
  抛出：
  
  IllegalStateException - 如果由于插入限制此时不能添加所有元素
  
  ClassCastException - 如果指定集合的元素的类阻止将其添加到此双端队列
  
  NullPointerException - 如果指定的集合包含空元素并且此双端队列不允许空元素，或者如果指定的集合为空
  
  IllegalArgumentException - 如果指定集合的元素的某些属性阻止将其添加到此双端队列
  
  参见：
  
  Collection.add(Object)
- push
  
  void push(E e)
  
  如果可以在不违反容量限制的情况下立即将元素推入此双端队列表示的堆栈（换句话说，在此双端队列的头部），如果当前没有可用空间，则抛出 IllegalStateException。
  此方法等效于 addFirst(E) 。
  
  参数：
  
  e - 要推送的元素
  
  抛出：
  
  IllegalStateException - 如果由于容量限制此时无法添加元素
  
  ClassCastException - 如果指定元素的类阻止将其添加到此双端队列
  
  NullPointerException - 如果指定元素为空且此双端队列不允许空元素
  
  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 - 如果指定元素的类与此双端队列不兼容 (optional)
  
  NullPointerException - 如果指定元素为 null 并且此双端队列不允许 null 元素 (optional)
- contains
  
  boolean contains(Object o)
  
  如果此双端队列包含指定元素，则返回 true。更正式地说，返回 true 当且仅当此双端队列包含至少一个元素 e 使得 Objects.equals(o, e) 。
  
  指定者：
  
  contains 在接口 Collection<E> 中
  
  参数：
  
  o - 要测试其在此双端队列中是否存在的元素
  
  返回：
  
  true 如果这个双端队列包含指定的元素
  
  抛出：
  
  ClassCastException - 如果指定元素的类与此双端队列不兼容 (optional)
  
  NullPointerException - 如果指定元素为 null 并且此双端队列不允许 null 元素 (optional)
- size
  
  int size()
  
  返回此双端队列中的元素数。
  
  指定者：
  
  size 在接口 Collection<E> 中
  
  返回：
  
  此双端队列中的元素数
- iterator
  
  Iterator <E > iterator()
  
  以正确的顺序返回此双端队列中元素的迭代器。元素将按从第一个（头）到最后一个（尾）的顺序返回。
  
  指定者：
  
  iterator 在接口 Collection<E> 中
  
  指定者：
  
  iterator 在接口 Iterable<E> 中
  
  返回：
  
  以适当顺序在此双端队列中的元素上的迭代器
- descendingIterator
  
  Iterator <E > descendingIterator()
  
  以相反的顺序返回此双端队列中元素的迭代器。元素将按从最后（尾）到第一个（头）的顺序返回。
  
  返回：
  
  以相反顺序遍历此双端队列中元素的迭代器

接口 Deque<E>

方法总结

在接口 java.util.Collection 中声明的方法

在接口 java.lang.Iterable 中声明的方法

方法详情

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