java.util
类 ArrayDeque<E>

java.lang.Object
  java.util.AbstractCollection<E>
      java.util.ArrayDeque<E>

类型参数：

E - the type of elements held in this collection

所有已实现的接口：

Serializable, Cloneable, Iterable<E>, Collection<E>, Deque<E>, Queue<E>

public class ArrayDeque<E>
extends AbstractCollection<E>
implements Deque<E>, Cloneable, Serializable

Deque 接口的大小可变数组的实现。数组双端队列没有容量限制；它们可根据需要增加以支持使用。它们不是线程安全的；在没有外部同步时，它们不支持多个线程的并发访问。禁止 null 元素。此类很可能在用作堆栈时快于 Stack，在用作队列时快于 LinkedList。

大多数 ArrayDeque 操作以摊销的固定时间运行。异常包括 remove、removeFirstOccurrence、removeLastOccurrence、contains、iterator.remove() 以及批量操作，它们均以线性时间运行。

此类的 iterator 方法返回的迭代器是快速失败 的：如果在创建迭代器后的任意时间通过除迭代器本身的 remove 方法之外的任何其他方式修改了双端队列，则迭代器通常将抛出 ConcurrentModificationException。因此，面对并发修改，迭代器很快就会完全失败，而不是冒着在将来不确定的时刻任意发生不确定行为的风险。

注意，迭代器的快速失败行为不能得到保证，一般来说，存在不同步的并发修改时，不可能作出任何坚决的保证。快速失败迭代器尽最大努力抛出 ConcurrentModificationException。因此，编写依赖于此异常的程序是错误的，正确做法是：迭代器的快速失败行为应该仅用于检测 bug。

此类及其迭代器实现 Collection 和 Iterator 接口的所有可选 方法。

此类是 Java Collections Framework 的成员。

从以下版本开始：

1.6

另请参见：

序列化表格

ArrayDeque

public ArrayDeque()

构造一个初始容量能够容纳 16 个元素的空数组双端队列。

ArrayDeque

public ArrayDeque(int numElements)

构造一个初始容量能够容纳指定数量的元素的空数组双端队列。

参数：

numElements - 双端队列初始容量的下边界

ArrayDeque

public ArrayDeque(Collection<? extends E> c)

构造一个包含指定 collection 的元素的双端队列，这些元素按 collection 的迭代器返回的顺序排列。（collection 迭代器返回的第一个元素将是第一个元素，或双端队列的开头。）

参数：

c - 要将其元素放入双端队列的 collection

抛出：

NullPointerException - 如果指定 collection 为 null

addFirst

public void addFirst(E e)

将指定元素插入此双端队列的开头。

指定者：

接口 Deque<E> 中的 addFirst

参数：

e - 要添加的元素

抛出：

NullPointerException - 如果指定元素为 null

addLast

public void addLast(E e)

将指定元素插入此双端队列的末尾。

此方法等效于 add(E)。

指定者：

接口 Deque<E> 中的 addLast

参数：

e - 要添加的元素

抛出：

NullPointerException - 如果指定元素为 null

offerFirst

public boolean offerFirst(E e)

将指定元素插入此双端队列的开头。

指定者：

接口 Deque<E> 中的 offerFirst

参数：

e - 要添加的元素

返回：

true （根据 Deque.offerFirst(E) 的规定）

抛出：

NullPointerException - 如果指定元素为 null

offerLast

public boolean offerLast(E e)

将指定元素插入此双端队列的末尾。

指定者：

接口 Deque<E> 中的 offerLast

参数：

e - 要添加的元素

返回：

true （根据 Deque.offerLast(E) 的规定）

抛出：

NullPointerException - 如果指定元素为 null

removeFirst

public E removeFirst()

从接口 Deque 复制的描述

获取并移除此双端队列第一个元素。此方法与 pollFirst 唯一的不同在于：如果此双端队列为空，它将抛出一个异常。

指定者：

接口 Deque<E> 中的 removeFirst

返回：

此双端队列的头部

抛出：

NoSuchElementException - 如果此双端队列为空

removeLast

public E removeLast()

从接口 Deque 复制的描述

获取并移除此双端队列的最后一个元素。此方法与 pollLast 唯一的不同在于：如果此双端队列为空，它将抛出一个异常。

指定者：

接口 Deque<E> 中的 removeLast

返回：

此双端队列的尾部

抛出：

NoSuchElementException - 如果此双端队列为空

pollFirst

public E pollFirst()

从接口 Deque 复制的描述

获取并移除此双端队列的第一个元素；如果此双端队列为空，则返回 null。

指定者：

接口 Deque<E> 中的 pollFirst

返回：

此双端队列的头部；如果此双端队列为空，则返回 null

pollLast

public E pollLast()

从接口 Deque 复制的描述

获取并移除此双端队列的最后一个元素；如果此双端队列为空，则返回 null。

指定者：

接口 Deque<E> 中的 pollLast

返回：

此双端队列的尾部；如果此双端队列为空，则返回 null

getFirst

public E getFirst()

从接口 Deque 复制的描述

获取，但不移除此双端队列的第一个元素。 此方法与 peekFirst 唯一的不同在于：如果此双端队列为空，它将抛出一个异常。

指定者：

接口 Deque<E> 中的 getFirst

返回：

此双端队列的头部

抛出：

NoSuchElementException - 如果此双端队列为空

getLast

public E getLast()

从接口 Deque 复制的描述

获取，但不移除此双端队列的最后一个元素。此方法与 peekLast 唯一的不同在于：如果此双端队列为空，它将抛出一个异常。

指定者：

接口 Deque<E> 中的 getLast

返回：

此双端队列的尾部

抛出：

NoSuchElementException - 如果此双端队列为空

peekFirst

public E peekFirst()

从接口 Deque 复制的描述

获取，但不移除此双端队列的第一个元素；如果此双端队列为空，则返回 null。

指定者：

接口 Deque<E> 中的 peekFirst

返回：

此双端队列的头部；如果此双端队列为空，则返回 null

peekLast

public E peekLast()

从接口 Deque 复制的描述

获取，但不移除此双端队列的最后一个元素；如果此双端队列为空，则返回 null。

指定者：

接口 Deque<E> 中的 peekLast

返回：

此双端队列的尾部；如果此双端队列为空，则返回 null

removeFirstOccurrence

public boolean removeFirstOccurrence(Object o)

移除此双端队列中第一次出现的指定元素（当从头部到尾部遍历双端队列时）。如果此双端队列不包含该元素，则不作更改。更确切地讲，移除第一个满足 o.equals(e) 的元素 e（如果存在这样的元素）。如果此双端队列包含指定的元素（或者此双端队列由于调用而发生了更改），则返回 true。

指定者：

接口 Deque<E> 中的 removeFirstOccurrence

参数：

o - 要从此双端队列中移除的元素（如果存在）

返回：

如果双端队列包含指定元素，则返回 true

removeLastOccurrence

public boolean removeLastOccurrence(Object o)

移除此双端队列中最后一次出现的指定元素（当从头部到尾部遍历双端队列时）。如果此双端队列不包含该元素，则不作更改。更确切地讲，移除最后一个满足 o.equals(e) 的元素 e（如果存在这样的元素）。如果此双端队列包含指定的元素（或者此双端队列由于调用而发生了更改），则返回 true。

指定者：

接口 Deque<E> 中的 removeLastOccurrence

参数：

o - 要从此双端队列中移除的元素（如果存在）

返回：

如果双端队列包含指定元素，则返回 true

add

public boolean add(E e)

将指定元素插入此双端队列的末尾。

此方法等效于 addLast(E)。

指定者：

接口 Collection<E> 中的 add

指定者：

接口 Deque<E> 中的 add

指定者：

接口 Queue<E> 中的 add

覆盖：

类 AbstractCollection<E> 中的 add

参数：

e - 要添加的元素

返回：

true （根据 Collection.add(E) 的规定）

抛出：

NullPointerException - 如果指定元素为 null

offer

public boolean offer(E e)

将指定元素插入此双端队列的末尾。

此方法等效于 offerLast(E)。

指定者：

接口 Deque<E> 中的 offer

指定者：

接口 Queue<E> 中的 offer

参数：

e - 要添加的元素

返回：

true（根据 Queue.offer(E) 的规定）

抛出：

NullPointerException - 如果指定元素为 null

remove

public E remove()

获取并移除此双端队列所表示的队列的头。 此方法与 poll 的不同之处在于：如果此双端队列为空，它将抛出一个异常。

此方法等效于 removeFirst()。

指定者：

接口 Deque<E> 中的 remove

指定者：

接口 Queue<E> 中的 remove

返回：

此双端队列所表示的队列的头

抛出：

NoSuchElementException - 如果此双端队列为空

poll

public E poll()

获取并移除此双端队列所表示的队列的头（换句话说，此双端队列的第一个元素）；如果此双端队列为空，则返回 null。

此方法等效于 pollFirst()。

指定者：

接口 Deque<E> 中的 poll

指定者：

接口 Queue<E> 中的 poll

返回：

此双端队列所表示的队列的头；如果此双端队列为空，则返回 null

element

public E element()

获取，但不移除此双端队列所表示的队列的头。此方法与 peek 的不同之处在于：如果此双端队列为空，它将抛出一个异常。

此方法等效于 getFirst()。

指定者：

接口 Deque<E> 中的 element

指定者：

接口 Queue<E> 中的 element

返回：

此双端队列所表示的队列的头

抛出：

NoSuchElementException - 如果此双端队列为空

peek

public E peek()

获取，但不移除此双端队列所表示的队列的头；如果此双端队列为空，则返回 null。

此方法等效于 peekFirst()。

指定者：

接口 Deque<E> 中的 peek

指定者：

接口 Queue<E> 中的 peek

返回：

此双端队列所表示的队列的头；如果此双端队列为空，则返回 null

push

public void push(E e)

将元素推入此双端队列所表示的堆栈。换句话说，将元素插入此双端队列的开头。

此方法等效于 addFirst(E)。

指定者：

接口 Deque<E> 中的 push

参数：

e - 要推入的元素

抛出：

NullPointerException - 如果指定元素为 null

pop

public E pop()

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

此方法等效于 removeFirst()。

指定者：

接口 Deque<E> 中的 pop

返回：

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

抛出：

NoSuchElementException - 如果此双端队列为空

size

public int size()

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

指定者：

接口 Collection<E> 中的 size

指定者：

接口 Deque<E> 中的 size

指定者：

类 AbstractCollection<E> 中的 size

返回：

此双端队列中的元素数

isEmpty

public boolean isEmpty()

如果此双端队列未包含任何元素，则返回 true。

指定者：

接口 Collection<E> 中的 isEmpty

覆盖：

类 AbstractCollection<E> 中的 isEmpty

返回：

如果此双端队列未包含任何元素，则返回 true

iterator

public Iterator<E> iterator()

返回在此双端队列的元素上进行迭代的迭代器。元素将按从第一个（头）到最后一个（尾）的顺序进行排序。这与元素出列（通过连续调用 remove()）或弹出（通过连续调用 pop()）的顺序相同。

指定者：

接口 Iterable<E> 中的 iterator

指定者：

接口 Collection<E> 中的 iterator

指定者：

接口 Deque<E> 中的 iterator

指定者：

类 AbstractCollection<E> 中的 iterator

返回：

在此双端队列的元素上进行迭代的迭代器

descendingIterator

public Iterator<E> descendingIterator()

从接口 Deque 复制的描述

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

指定者：

接口 Deque<E> 中的 descendingIterator

返回：

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

contains

public boolean contains(Object o)

如果此双端队列包含指定元素，则返回 true。更确切地讲，当且仅当此双端队列至少包含一个满足 o.equals(e) 的元素 e 时，返回 true。

指定者：

接口 Collection<E> 中的 contains

指定者：

接口 Deque<E> 中的 contains

覆盖：

类 AbstractCollection<E> 中的 contains

参数：

o - 检查是否包含于此双端队列的对象

返回：

如果此双端队列包含指定的元素，则返回 true。

remove

public boolean remove(Object o)

从此双端队列中移除指定元素的单个实例。如果此双端队列不包含该元素，则不作更改。更确切地讲，移除第一个满足 o.equals(e) 的元素 e（如果存在这样的元素）。如果此双端队列包含指定的元素（或者此双端队列由于调用而发生了更改），则返回 true。

此方法等效于 removeFirstOccurrence(java.lang.Object)。

指定者：

接口 Collection<E> 中的 remove

指定者：

接口 Deque<E> 中的 remove

覆盖：

类 AbstractCollection<E> 中的 remove

参数：

o - 要从此双端队列中移除的元素（如果存在）

返回：

如果此双端队列包含指定元素，则返回 true

clear

public void clear()

从此双端队列中移除所有元素。在此调用返回之后，该双端队列将为空。

指定者：

接口 Collection<E> 中的 clear

覆盖：

类 AbstractCollection<E> 中的 clear

toArray

public Object[] toArray()

返回一个以恰当顺序包含此双端队列所有元素的数组（从第一个元素到最后一个元素）。

由于此双端队列不维护对返回数组的任何引用，因而它将是“安全的”。（换句话说，此方法必须分配一个新的数组）。因此，调用者可以自由地修改返回的数组。

此方法充当了基于数组的 API 与基于 collection 的 API 之间的桥梁。

指定者：

接口 Collection<E> 中的 toArray

覆盖：

类 AbstractCollection<E> 中的 toArray

返回：

包含此双端队列中所有元素的数组。

toArray

public <T> T[] toArray(T[] a)

返回一个以恰当顺序包含此双端队列所有元素的数组（从第一个元素到最后一个元素）；返回数组的运行时类型是指定数组的运行时类型。如果指定的数组能容纳双端队列，则将它返回此处。否则，将分配一个具有指定数组的运行时类型和此双端队列大小的新数组。

如果指定的数组能容纳此双端队列，并有剩余的空间（即数组的元素比此双端队列多），那么将数组中紧接双端队列尾部的元素设置为 null。

像 toArray() 方法一样，此方法充当基于数组的 API 与基于 collection 的 API 之间的桥梁。更进一步说，此方法允许对输出数组的运行时类型进行精确控制，在某些情况下，还可以用来节省分配开销。

假定 x 是只包含字符串的一个已知双端队列。以下代码可用来将该双端队列转储到一个新分配的 String 数组：

String[] y = x.toArray(new String[0]);

注意，toArray(new Object[0]) 和 toArray() 在功能上是相同的。

指定者：

接口 Collection<E> 中的 toArray

覆盖：

类 AbstractCollection<E> 中的 toArray

参数：

a - 要用来存储双端队列元素的数组（如果该数组足够大）；否则，将为此分配一个具有相同运行时类型的新数组

返回：

包含此双端队列所有元素的数组

抛出：

ArrayStoreException - 如果指定数组的运行时类型不是此双端队列每个元素的运行时类型的超类型

NullPointerException - 如果指定的数组为 null

clone

public ArrayDeque<E> clone()

返回此双端队列的副本。

覆盖：

类 Object 中的 clone

返回：

此双端队列的副本

另请参见：

Cloneable

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。