JavaTM Platform
Standard Ed. 6

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 操作以摊销的固定时间运行。异常包括 removeremoveFirstOccurrenceremoveLastOccurrencecontainsiterator.remove() 以及批量操作,它们均以线性时间运行。

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

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

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

此类是 Java Collections Framework 的成员。

从以下版本开始:
1.6
另请参见:
序列化表格

构造方法摘要
ArrayDeque()
          构造一个初始容量能够容纳 16 个元素的空数组双端队列。
ArrayDeque(Collection<? extends E> c)
          构造一个包含指定 collection 的元素的双端队列,这些元素按 collection 的迭代器返回的顺序排列。
ArrayDeque(int numElements)
          构造一个初始容量能够容纳指定数量的元素的空数组双端队列。
 
方法摘要
 boolean add(E e)
          将指定元素插入此双端队列的末尾。
 void addFirst(E e)
          将指定元素插入此双端队列的开头。
 void addLast(E e)
          将指定元素插入此双端队列的末尾。
 void clear()
          从此双端队列中移除所有元素。
 ArrayDeque<E> clone()
          返回此双端队列的副本。
 boolean contains(Object o)
          如果此双端队列包含指定元素,则返回 true
 Iterator<E> descendingIterator()
          返回以逆向顺序在此双端队列的元素上进行迭代的迭代器。
 E element()
          获取,但不移除此双端队列所表示的队列的头。
 E getFirst()
          获取,但不移除此双端队列的第一个元素。
 E getLast()
          获取,但不移除此双端队列的最后一个元素。
 boolean isEmpty()
          如果此双端队列未包含任何元素,则返回 true
 Iterator<E> iterator()
          返回在此双端队列的元素上进行迭代的迭代器。
 boolean offer(E e)
          将指定元素插入此双端队列的末尾。
 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)
          将元素推入此双端队列所表示的堆栈。
 E remove()
          获取并移除此双端队列所表示的队列的头。
 boolean remove(Object o)
          从此双端队列中移除指定元素的单个实例。
 E removeFirst()
          获取并移除此双端队列第一个元素。
 boolean removeFirstOccurrence(Object o)
          移除此双端队列中第一次出现的指定元素(当从头部到尾部遍历双端队列时)。
 E removeLast()
          获取并移除此双端队列的最后一个元素。
 boolean removeLastOccurrence(Object o)
          移除此双端队列中最后一次出现的指定元素(当从头部到尾部遍历双端队列时)。
 int size()
          返回此双端队列中的元素数。
 Object[] toArray()
          返回一个以恰当顺序包含此双端队列所有元素的数组(从第一个元素到最后一个元素)。
<T> T[]
toArray(T[] a)
          返回一个以恰当顺序包含此双端队列所有元素的数组(从第一个元素到最后一个元素);返回数组的运行时类型是指定数组的运行时类型。
 
从类 java.util.AbstractCollection 继承的方法
addAll, containsAll, removeAll, retainAll, toString
 
从类 java.lang.Object 继承的方法
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
从接口 java.util.Collection 继承的方法
addAll, containsAll, equals, hashCode, removeAll, retainAll
 

构造方法详细信息

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

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

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