Deque (Java Platform SE 8 )

参数类型

E - 在此集合中保存的元素的类型

All Superinterfaces:

Collection <E>， Iterable <E>， Queue <E>

All Known Subinterfaces:

BlockingDeque <E>

所有已知实现类：

ArrayDeque ， ConcurrentLinkedDeque ， LinkedBlockingDeque ， LinkedList
```
public interface Deque<E>
extends Queue<E>
```
支持两端元素插入和移除的线性集合。名称deque是“双端队列”的缩写，通常发音为“deck”。大多数Deque实现对它们可能包含的元素的数量没有固定的限制，但是该接口支持容量限制的deques以及没有固定大小限制的deques。
该界面定义了访问deque两端元素的方法。提供了插入，移除和检查元素的方法。这些方法中的每一种存在两种形式：如果操作失败，则会抛出异常，另一种方法返回一个特殊值（ null或false ，具体取决于操作）。插入操作的后一种形式专门设计用于容量限制的Deque实现; 在大多数实现中，插入操作不能失败。

上述十二种方法总结在下表中：
Summary of Deque methods First Element (Head) Last Element (Tail) Throws exception Special value Throws exception Special value Insert addFirst(e) offerFirst(e) addLast(e) offerLast(e) Remove removeFirst() pollFirst() removeLast() pollLast() Examine getFirst() peekFirst() getLast() peekLast()

此接口扩展了Queue接口。当使用deque作为队列时，FIFO（先进先出）行为的结果。元素将添加到deque的末尾，并从头开始删除。从Queue接口Deque方法正好等同于下表所示的Deque方法：
Comparison of Queue and Deque methods Queue Method Equivalent Deque Method add(e) addLast(e) offer(e) offerLast(e) remove() removeFirst() poll() pollFirst() element() getFirst() peek() peekFirst()

Deques也可以用作LIFO（先进先出）堆栈。这个接口应该优先于传统的Stack类。当一个deque作为一个堆栈时，元素从deque的开头被推出并弹出。堆栈方法正好等同于下表所示的Deque方法：
Comparison of Stack and Deque methods Stack Method Equivalent Deque Method push(e) addFirst(e) pop() removeFirst() peek() peekFirst()

请注意，当使用deque作为队列或堆栈时， peek方法同样适用; 在任何一种情况下，元素都是从德甲开始绘出的。

该界面提供了两种方法去除内部元素， removeFirstOccurrence和removeLastOccurrence 。

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

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

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

此接口是成员Java Collections Framework 。

从以下版本开始：

1.6

方法摘要

所有方法接口方法抽象方法
Modifier and Type	Method and Description
`boolean`	`add(E e)` 将指定的元素插入此双端队列表示的队列中（换句话说，在此双端队列的尾部），如果它是立即可行且不会违反容量限制，返回 `true`在成功时和抛出 `IllegalStateException`如果当前没有空间可用的。
`void`	`addFirst(E e)` 插入此双端队列的前面，如果它是立即可行且不会违反容量限制，抛出一个指定的元素 `IllegalStateException`如果当前没有空间可用。
`void`	`addLast(E e)` 在插入如果它是立即可行且不会违反容量限制，抛出此双端队列的末尾指定元素 `IllegalStateException`如果当前没有空间可用。
`boolean`	`contains(Object o)` 如果此deque包含指定的元素，则返回 `true` 。
`Iterator<E>`	`descendingIterator()` 以相反的顺序返回此deque中的元素的迭代器。
`E`	`element()` 检索但不删除由此deque表示的队列的头部（换句话说，该deque的第一个元素）。
`E`	`getFirst()` 检索，但不删除，这个deque的第一个元素。
`E`	`getLast()` 检索，但不删除，这个deque的最后一个元素。
`Iterator<E>`	`iterator()` 以正确的顺序返回此deque中的元素的迭代器。
`boolean`	`offer(E e)` 将指定的元素插入由此deque表示的队列（换句话说，在该deque的尾部），如果可以立即执行，而不违反容量限制， `true`在成功时 `false`如果当前没有可用空间，则返回false。
`boolean`	`offerFirst(E e)` 在此deque的前面插入指定的元素，除非它会违反容量限制。
`boolean`	`offerLast(E e)` 在此deque的末尾插入指定的元素，除非它会违反容量限制。
`E`	`peek()` 检索但不删除由此deque表示的队列的头部（换句话说，此deque的第一个元素），如果此deque为空，则返回 `null` 。
`E`	`peekFirst()` 检索，但不删除，此deque的第一个元素，或返回 `null`如果这个deque是空的。
`E`	`peekLast()` 检索但不删除此deque的最后一个元素，如果此deque为空，则返回 `null` 。
`E`	`poll()` 检索并删除由此deque（换句话说，此deque的第一个元素）表示的队列的 `null`如果此deque为空，则返回 `null` 。
`E`	`pollFirst()` 检索并删除此deque的第一个元素，如果此deque为空，则返回 `null` 。
`E`	`pollLast()` 检索并删除此deque的最后一个元素，如果此deque为空，则返回 `null` 。
`E`	`pop()` 从这个deque表示的堆栈中弹出一个元素。
`void`	`push(E e)` 将元素推送到由此deque表示的堆栈（换句话说，在此deque的头部），如果可以立即执行此操作而不违反容量限制，则抛出 `IllegalStateException`如果当前没有可用空间）。
`E`	`remove()` 检索并删除由此deque表示的队列的头（换句话说，该deque的第一个元素）。
`boolean`	`remove(Object o)` 从此deque中删除指定元素的第一个出现。
`E`	`removeFirst()` 检索并删除此deque的第一个元素。
`boolean`	`removeFirstOccurrence(Object o)` 从此deque中删除指定元素的第一个出现。
`E`	`removeLast()` 检索并删除此deque的最后一个元素。
`boolean`	`removeLastOccurrence(Object o)` 从此deque中删除指定元素的最后一次出现。
`int`	`size()` 返回此deque中的元素数。

Methods inherited from interface java.util.Collection
addAll, clear, containsAll, equals, hashCode, isEmpty, parallelStream, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray

Methods inherited from interface java.lang.Iterable
forEach

- 方法详细信息
  - addFirst
```
void addFirst(E e)
```
    插入此双端队列的前面，如果它是立即可行且不会违反容量限制，抛出一个指定的元素IllegalStateException如果当前没有空间可用。当使用容量限制的deque时，通常最好使用方法offerFirst(E) 。
    
    参数
    
    e - 要添加的元素
    
    异常
    
    IllegalStateException - 如果由于容量限制，此时无法添加该元素
    
    ClassCastException - 如果指定元素的类阻止将其添加到此deque
    
    NullPointerException - 如果指定的元素为空，并且该deque不允许空元素
    
    IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此deque
  - addLast
```
void addLast(E e)
```
    在插入如果它是立即可行且不会违反容量限制，抛出此双端队列的末尾指定元素IllegalStateException如果当前没有空间可用。当使用容量限制的deque时，通常最好使用方法offerLast(E) 。
    此方法相当于add(E) 。
    
    参数
    
    e - 要添加的元素
    
    异常
    
    IllegalStateException - 如果由于容量限制，此时无法添加该元素
    
    ClassCastException - 如果指定元素的类阻止将其添加到此deque
    
    NullPointerException - 如果指定的元素为空，此deque不允许空元素
    
    IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此deque
  - offerFirst
```
boolean offerFirst(E e)
```
    在此deque的前面插入指定的元素，除非它会违反容量限制。当使用有容量限制的双端队列，这种方法通常是优选的addFirst(E)方法，其能够仅失败通过抛出异常来插入的元件。
    
    参数
    
    e - 要添加的元素
    
    结果
    
    true如果元素被添加到这个deque，否则 false
    
    异常
    
    ClassCastException - 如果指定元素的类阻止它添加到此deque
    
    NullPointerException - 如果指定的元素为空，此deque不允许空元素
    
    IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此deque
  - offerLast
```
boolean offerLast(E e)
```
    在此deque的末尾插入指定的元素，除非它会违反容量限制。当使用有容量限制的双端队列，这种方法通常是优选的addLast(E)方法，其能够仅失败通过抛出异常来插入的元件。
    
    参数
    
    e - 要添加的元素
    
    结果
    
    true如果元素被添加到这个deque，否则 false
    
    异常
    
    ClassCastException - 如果指定元素的类阻止它添加到此deque
    
    NullPointerException - 如果指定的元素为空，并且该deque不允许空元素
    
    IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此deque
  - removeFirst
```
E removeFirst()
```
    检索并删除此deque的第一个元素。此方法与pollFirst不同之处在于，如果此deque为空，它将抛出异常。
    
    结果
    
    这个德克的头
    
    异常
    
    NoSuchElementException - 如果这个deque是空的
  - removeLast
```
E removeLast()
```
    检索并删除此deque的最后一个元素。此方法与pollLast不同之处在于，如果此deque为空，它将抛出异常。
    
    结果
    
    这个德克的尾巴
    
    异常
    
    NoSuchElementException - 如果这个deque是空的
  - pollFirst
```
E pollFirst()
```
    检索并删除此deque的第一个元素，如果此deque为空，则返回 null 。
    
    结果
    
    这个deque的头，或 null如果这个deque是空的
  - pollLast
```
E pollLast()
```
    检索并删除此deque的最后一个元素，如果此deque为空，则返回 null 。
    
    结果
    
    这个deque的尾巴，或 null如果这个deque是空的
  - getFirst
```
E getFirst()
```
    检索，但不删除，这个deque的第一个元素。此方法与peekFirst的不同之处在于，如果此deque为空，它将抛出异常。
    
    结果
    
    这个德克的头
    
    异常
    
    NoSuchElementException - 如果这个deque是空的
  - getLast
```
E getLast()
```
    检索，但不删除，这个deque的最后一个元素。此方法与peekLast不同之处在于，如果此deque为空，它将抛出异常。
    
    结果
    
    这个德克的尾巴
    
    异常
    
    NoSuchElementException - 如果这个deque是空的
  - peekFirst
```
E peekFirst()
```
    检索，但不删除，这个deque的第一个元素，或返回 null如果这个deque是空的。
    
    结果
    
    这个deque的头，或 null如果这个deque是空的
  - peekLast
```
E peekLast()
```
    检索但不删除此deque的最后一个元素，或返回 null如果此deque为空）。
    
    结果
    
    这个deque的尾巴，或 null如果这个deque是空的
  - removeFirstOccurrence
```
boolean removeFirstOccurrence(Object o)
```
    从此deque中删除指定元素的第一个出现。如果deque不包含元素，则它不变。更正式地，删除第一元素e ，使得(o==null ? e==null : o.equals(e)) （如果这样的元素存在）。如果此deque包含指定的元素（或等效地，如果此deque因呼叫而改变），则返回true 。
    
    参数
    
    o - 要从此deque移除的元素（如果存在）
    
    结果
    
    true如果某个元素因此调用而被删除
    
    异常
    
    ClassCastException - 如果指定元素的类与此deque不兼容（ optional ）
    
    NullPointerException - 如果指定的元素为空，并且此deque不允许空元素（ optional ）
  - removeLastOccurrence
```
boolean removeLastOccurrence(Object o)
```
    从此deque中删除指定元素的最后一次出现。如果deque不包含元素，则它不变。更正式地，删除最后一个元素e ，使(o==null ? e==null : o.equals(e)) （如果这样的元素存在）。如果此deque包含指定的元素（或等效地，如果此deque由于调用而更改），则返回true 。
    
    参数
    
    o - 要从此deque移除的元素（如果存在）
    
    结果
    
    true如果一个元素被删除作为这个调用的结果
    
    异常
    
    ClassCastException - 如果指定元素的类与此deque不兼容（ optional ）
    
    NullPointerException - 如果指定的元素为空，此deque不允许空元素（ optional ）
  - add
```
boolean add(E e)
```
    将指定的元素插入由此deque（换句话说，在该deque的尾部）表示的队列中，如果可以立即执行此操作而不违反容量限制， true在成功后返回IllegalStateException如果当前没有可用空间，则抛出IllegalStateException 。当使用容量限制的deque时，通常最好使用offer 。
    此方法相当于addLast(E) 。
    
    Specified by:
    
    add在界面 Collection<E>
    
    Specified by:
    
    add在界面 Queue<E>
    
    参数
    
    e - 要添加的元素
    
    结果
    
    true （由 Collection.add(E)指定）
    
    异常
    
    IllegalStateException - 如果由于容量限制，此时无法添加该元素
    
    ClassCastException - 如果指定元素的类阻止它添加到此deque
    
    NullPointerException - 如果指定的元素为空，并且该deque不允许空元素
    
    IllegalArgumentException - 如果指定元素的某些属性阻止其添加到此deque
  - offer
```
boolean offer(E e)
```
    将指定的元素插入由此deque（换句话说，在该deque的尾部）表示的队列中，如果可以立即执行，而不违反容量限制， true在成功时false如果当前没有可用空间，则返回false。当使用有容量限制的双端队列，这种方法通常是优选的add(E)方法，其能够仅失败通过抛出异常来插入的元件。
    此方法相当于offerLast(E) 。
    
    Specified by:
    
    offer在界面 Queue<E>
    
    参数
    
    e - 要添加的元素
    
    结果
    
    true如果元素被添加到这个deque，否则 false
    
    异常
    
    ClassCastException - 如果指定元素的类阻止它添加到此deque
    
    NullPointerException - 如果指定的元素为空，并且此deque不允许空元素
    
    IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此deque
  - remove
```
E remove()
```
    检索并删除由此deque表示的队列的头（换句话说，该deque的第一个元素）。此方法与poll不同之处在于，如果此deque为空，它将抛出异常。
    此方法相当于removeFirst() 。
    
    Specified by:
    
    remove在界面 Queue<E>
    
    结果
    
    由这个德克队代表的队列的头
    
    异常
    
    NoSuchElementException - 如果这个deque是空的
  - poll
```
E poll()
```
    检索并删除由此deque（换句话说，该deque的第一个元素）表示的队列的头，或者如果此deque为空，则返回null 。
    这个方法相当于pollFirst() 。
    
    Specified by:
    
    poll在界面 Queue<E>
    
    结果
    
    这个deque的第一个元素，或 null如果这个deque是空的
  - element
```
E element()
```
    检索但不删除由此deque表示的队列的头部（换句话说，该deque的第一个元素）。此方法与peek不同之处在于，如果此deque为空，它将抛出异常。
    这个方法相当于getFirst() 。
    
    Specified by:
    
    element在界面 Queue<E>
    
    结果
    
    由这个德克队代表的队列的头
    
    异常
    
    NoSuchElementException - 如果这个deque是空的
  - peek
```
E peek()
```
    检索但不删除由此deque表示的队列的头部（换句话说，该deque的第一个元素），如果此deque为空，则返回null 。
    此方法相当于peekFirst() 。
    
    Specified by:
    
    peek在界面 Queue<E>
    
    结果
    
    由这个deque代表的队列的头，或者如果这个deque是空的话，那么是 null
  - push
```
void push(E e)
```
    将元素推送到由此deque表示的堆栈（换句话说，在此deque的头部），如果可能立即执行此操作而不违反容量限制，则抛出IllegalStateException如果当前没有可用空间）。
    此方法相当于addFirst(E) 。
    
    参数
    
    e - 要推的元素
    
    异常
    
    IllegalStateException - 如果由于容量限制，此时无法添加该元素
    
    ClassCastException - 如果指定元素的类阻止将其添加到此deque
    
    NullPointerException - 如果指定的元素为空，并且此deque不允许空元素
    
    IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此deque
  - pop
```
E pop()
```
    从这个deque表示的堆栈中弹出一个元素。换句话说，删除并返回此deque的第一个元素。
    此方法相当于removeFirst() 。
    
    结果
    
    这个deque前面的元素（它是由这个deque表示的堆栈的顶部）
    
    异常
    
    NoSuchElementException - 如果这个deque是空的
  - remove
```
boolean remove(Object o)
```
    从此deque中删除指定元素的第一个出现。如果deque不包含元素，则它不变。更正式地，删除第一个元素e使得(o==null ? e==null : o.equals(e)) （如果这样的元素存在）。如果此deque包含指定的元素（或等效地，如果此deque由于调用而更改），则返回true 。
    此方法相当于removeFirstOccurrence(Object) 。
    
    Specified by:
    
    remove在界面 Collection<E>
    
    参数
    
    o - 要从此deque移除的元素（如果存在）
    
    结果
    
    true如果某个元素因此调用而被删除
    
    异常
    
    ClassCastException - 如果指定元素的类与此deque不兼容（ optional ）
    
    NullPointerException - 如果指定的元素为空，此deque不允许空元素（ optional ）
  - contains
```
boolean contains(Object o)
```
    如果此deque包含指定的元素，则返回true 。更正式地说，返回true当且仅当此双端队列至少包含一个元素e这样(o==null ? e==null : o.equals(e))。
    
    Specified by:
    
    contains在界面 Collection<E>
    
    参数
    
    o - 要在此deque中存在的元素要进行测试
    
    结果
    
    true如果这个deque包含指定的元素
    
    异常
    
    ClassCastException - 如果指定元素的类型与此deque不兼容（ optional ）
    
    NullPointerException - 如果指定的元素为空，并且此deque不允许空元素（ optional ）
  - size
```
int size()
```
    返回此deque中的元素数。
    
    Specified by:
    
    size在界面 Collection<E>
    
    结果
    
    这个deque中的元素数量
  - iterator
```
Iterator<E> iterator()
```
    以正确的顺序返回此deque中的元素的迭代器。元素将按照从头（头）到最后（尾）的顺序返回。
    
    Specified by:
    
    iterator在界面 Collection<E>
    
    Specified by:
    
    iterator在界面 Iterable<E>
    
    结果
    
    在这个deque中的元素以适当的顺序迭代
  - descendingIterator
```
Iterator<E> descendingIterator()
```
    以相反的顺序返回此deque中的元素的迭代器。元素将从最后（尾）到第一（头）的顺序返回。
    
    结果
    
    在这个deque中的元素的反向迭代器

Interface Deque<E>

方法摘要

Methods inherited from interface java.util.Collection

Methods inherited from interface java.lang.Iterable

方法详细信息

addFirst

addLast

offerFirst

offerLast

removeFirst

removeLast

pollFirst

pollLast

getFirst

getLast

peekFirst

peekLast

removeFirstOccurrence

removeLastOccurrence

add

offer

remove

poll

element

peek

push

pop

remove

contains

size

iterator

descendingIterator