java.util
接口 Deque

类型参数：

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 种方法：

此接口扩展了 Queue 接口。在将双端队列用作队列时，将得到 FIFO（先进先出）行为。将元素添加到双端队列的末尾，从双端队列的开头移除元素。从 Queue 接口继承的方法完全等效于 Deque 方法，如下表所示：

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

注意，在将双端队列用作队列或堆栈时，peek 方法同样正常工作；无论哪种情况下，都从双端队列的开头抽取元素。

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

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

虽然 Deque 实现没有严格要求禁止插入 null 元素，但建议最好这样做。建议任何事实上允许 null 元素的 Deque 实现用户最好不 要利用插入 null 的功能。这是因为各种方法会将 null 用作特殊的返回值来指示双端队列为空。

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

此接口是 Java Collections Framework 的成员。

从以下版本开始：

1.6

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

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

返回：

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