Module java.base
Package java.util

Class ArrayDeque<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.ArrayDeque<E>
类型参数:
E - 此双端队列中保存的元素类型
所有实现的接口:
Serializable, Cloneable, Iterable<E>, Collection<E>, Deque<E>, Queue<E>, SequencedCollection<E>
public class ArrayDeque<E> extends AbstractCollection<E> implements Deque<E>, Cloneable, Serializable
Deque 接口的可调整大小数组实现。数组双端队列没有容量限制；它们会根据需要增长以支持使用。它们不是线程安全的；在没有外部同步的情况下，它们不支持多个线程的并发访问。禁止使用空元素。当作为堆栈使用时，此类可能比 Stack 更快，当作为队列使用时，可能比 LinkedList 更快。

大多数 ArrayDeque 操作的平摊时间为常数。异常包括 remove、removeFirstOccurrence、removeLastOccurrence、contains、iterator.remove() 和批量操作，这些操作都需要线性时间。

此类的 iterator 方法返回的迭代器是 快速失败 的：如果在创建迭代器后的任何时间修改了双端队列，除了通过迭代器自己的 remove 方法之外的任何方式，迭代器通常会抛出 ConcurrentModificationException。因此，在面对并发修改时，迭代器会快速且干净地失败，而不是在未来的某个不确定时间冒险进行任意的、非确定性的行为。

请注意，迭代器的快速失败行为无法保证，因为一般来说，在存在未同步的并发修改的情况下，不可能做出任何硬性保证。快速失败迭代器尽力抛出 ConcurrentModificationException。因此，编写依赖此异常正确性的程序是错误的：迭代器的快速失败行为应仅用于检测错误。

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

此类是 Java 集合框架 的成员。

自 JDK 版本:
1.6
参见:

  • Constructor Summary

    Constructors
    Constructor
    Description
    ArrayDeque()
    构造一个初始容量足以容纳 16 个元素的空数组双端队列。
    ArrayDeque(int numElements)
    构造一个初始容量足以容纳指定数量元素的空数组双端队列。
    ArrayDeque(Collection<? extends E> c)
    构造一个包含指定集合元素的双端队列，元素顺序与集合迭代器返回的顺序相同。

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    add(E e)
    在此双端队列的末尾插入指定元素。
    boolean
    addAll(Collection<? extends E> c)
    将指定集合中的所有元素按照集合迭代器返回的顺序依次添加到此双端队列的末尾，就好像对每个元素调用 addLast(E) 一样。
    void
    addFirst(E e)
    在此双端队列的前面插入指定元素。
    void
    addLast(E e)
    在此双端队列的末尾插入指定元素。
    void
    clear()
    从此双端队列中移除所有元素。
    ArrayDeque<E>
    clone()
    返回此双端队列的副本。
    boolean
    contains(Object o)
    如果此双端队列包含指定元素，则返回 true。
    Iterator<E>
    descendingIterator()
    返回此双端队列中元素的逆序顺序的迭代器。
    E
    element()
    检索但不移除由此双端队列表示的队列的头部。
    void
    forEach(Consumer<? super E> action)
    对 Iterable 的每个元素执行给定操作，直到所有元素都已处理或操作引发异常。
    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)
    从此双端队列中移除指定元素的单个实例。
    boolean
    removeAll(Collection<?> c)
    移除此集合中包含在指定集合中的所有元素（可选操作）。
    E
    removeFirst()
    检索并移除此双端队列的第一个元素。
    boolean
    removeFirstOccurrence(Object o)
    移除此双端队列中指定元素的第一个出现（从头到尾遍历双端队列时）。
    boolean
    removeIf(Predicate<? super E> filter)
    移除满足给定谓词的此集合的所有元素。
    E
    removeLast()
    检索并移除此双端队列的最后一个元素。
    boolean
    removeLastOccurrence(Object o)
    移除此双端队列中指定元素的最后一个出现（从头到尾遍历双端队列时）。
    boolean
    retainAll(Collection<?> c)
    仅保留此集合中包含在指定集合中的元素（可选操作）。
    int
    size()
    返回此双端队列中的元素数量。
    Spliterator<E>
    spliterator()
    在此双端队列中的元素上创建一个 延迟绑定 和 快速失败 的 Spliterator。
    Object[]
    toArray()
    返回一个数组，其中包含此双端队列中所有元素的正确顺序（从第一个到最后一个元素）。
    <T> T[]
    toArray(T[] a)
    返回一个数组，其中包含此双端队列中所有元素的正确顺序（从第一个到最后一个元素）；返回的数组的运行时类型与指定数组的类型相同。

    Methods declared in class java.util.AbstractCollection

    containsAll, toString

    Methods declared in class java.lang.Object

    equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods declared in interface java.util.Collection

    containsAll, equals, hashCode, parallelStream, stream, toArray

    Methods declared in interface java.util.Deque

    reversed

  • Constructor Details

    • ArrayDeque

      public ArrayDeque()
      构造一个初始容量足以容纳 16 个元素的空数组双端队列。

    • ArrayDeque

      public ArrayDeque(int numElements)
      构造一个初始容量足以容纳指定数量元素的空数组双端队列。
      参数:
      numElements - 双端队列的初始容量下限

    • ArrayDeque

      public ArrayDeque(Collection<? extends E> c)
      构造一个包含指定集合元素的双端队列，元素顺序与集合迭代器返回的顺序相同（集合迭代器返回的第一个元素成为双端队列的第一个元素，或 前端）。
      参数:
      c - 要放入双端队列中的元素的集合
      抛出:
      NullPointerException - 如果指定的集合为 null

  • Method Details

    • addFirst

      public void addFirst(E e)
      在此双端队列的前面插入指定元素。
      指定者:
      addFirst 在接口 Deque<E> 中指定
      指定者:
      addFirst 在接口 SequencedCollection<E> 中指定
      参数:
      e - 要添加的元素
      抛出:
      NullPointerException - 如果指定的元素为 null

    • addLast

      public void addLast(E e)
      在此双端队列的末尾插入指定元素。

      此方法等效于 add(E)。

      指定由：
      addLast 在接口 Deque<E>中
      指定由：
      addLast 在接口 SequencedCollection<E>中
      参数：
      e - 要添加的元素
      抛出：
      NullPointerException - 如果指定的元素为null

    • addAll

      public boolean addAll(Collection<? extends E> c)
      将指定集合中的所有元素添加到此双端队列的末尾，就好像在集合的迭代器返回它们的顺序中调用addLast(E)一样。
      指定由：
      addAll 在接口 Collection<E>中
      指定由：
      addAll 在接口 Deque<E>中
      覆盖：
      addAll 在类 AbstractCollection<E>中
      参数：
      c - 要插入到此双端队列中的元素
      返回：
      true 如果调用导致此双端队列发生更改
      抛出：
      NullPointerException - 如果指定的集合或其任何元素为null
      参见：

    • offerFirst

      public boolean offerFirst(E e)
      将指定元素插入到此双端队列的前面。
      指定由：
      offerFirst 在接口 Deque<E>中
      参数：
      e - 要添加的元素
      返回：
      true（如Deque.offerFirst(E)指定的那样）
      抛出：
      NullPointerException - 如果指定的元素为null

    • offerLast

      public boolean offerLast(E e)
      将指定元素插入到此双端队列的末尾。
      指定由：
      offerLast 在接口 Deque<E>中
      参数：
      e - 要添加的元素
      返回：
      true（如Deque.offerLast(E)指定的那样）
      抛出：
      NullPointerException - 如果指定的元素为null

    • removeFirst

      public E removeFirst()
      从接口复制的描述： Deque
      检索并删除此双端队列的第一个元素。此方法与pollFirst的不同之处仅在于，如果此双端队列为空，则会抛出异常。
      指定由：
      removeFirst 在接口 Deque<E>中
      指定由：
      removeFirst 在接口 SequencedCollection<E>中
      返回：
      此双端队列的头部
      抛出：
      NoSuchElementException - 如果此双端队列为空

    • removeLast

      public E removeLast()
      从接口复制的描述： Deque
      检索并删除此双端队列的最后一个元素。此方法与pollLast的不同之处仅在于，如果此双端队列为空，则会抛出异常。
      指定由：
      removeLast 在接口 Deque<E>中
      指定由：
      removeLast 在接口 SequencedCollection<E>中
      返回：
      此双端队列的尾部
      抛出：
      NoSuchElementException - 如果此双端队列为空

    • pollFirst

      public E pollFirst()
      从接口复制的描述： Deque
      检索并删除此双端队列的第一个元素，如果此双端队列为空，则返回null。
      指定由：
      pollFirst 在接口 Deque<E>中
      返回：
      此双端队列的头部，如果此双端队列为空，则返回null

    • pollLast

      public E pollLast()
      从接口复制的描述： Deque
      检索并删除此双端队列的最后一个元素，如果此双端队列为空，则返回null。
      指定由：
      pollLast 在接口 Deque<E>中
      返回：
      此双端队列的尾部，如果此双端队列为空，则返回null

    • getFirst

      public E getFirst()
      从接口复制的描述： Deque
      检索但不删除此双端队列的第一个元素。此方法与peekFirst的不同之处仅在于，如果此双端队列为空，则会抛出异常。
      指定由：
      getFirst 在接口 Deque<E>中
      指定由：
      getFirst 在接口 SequencedCollection<E>中
      返回：
      此双端队列的头部
      抛出：
      NoSuchElementException - 如果此双端队列为空

    • getLast

      public E getLast()
      从接口复制的描述： Deque
      检索但不删除此双端队列的最后一个元素。此方法与peekLast的不同之处仅在于，如果此双端队列为空，则会抛出异常。
      指定由：
      getLast 在接口 Deque<E>中
      指定由：
      getLast 在接口 SequencedCollection<E>中
      返回：
      此双端队列的尾部
      抛出：
      NoSuchElementException - 如果此双端队列为空

    • peekFirst

      public E peekFirst()
      从接口复制的描述： Deque
      检索但不删除此双端队列的第一个元素，如果此双端队列为空，则返回null。
      指定由：
      peekFirst 在接口 Deque<E>中
      返回：
      此双端队列的头部，如果此双端队列为空，则返回null

    • peekLast

      public E peekLast()
      从接口复制的描述： Deque
      检索但不删除此双端队列的最后一个元素，如果此双端队列为空，则返回null。
      指定由：
      peekLast 在接口 Deque<E>
      返回：
      此双端队列的尾部，如果此双端队列为空则返回null

    • removeFirstOccurrence

      public boolean removeFirstOccurrence(Object o)
      从此双端队列中删除指定元素的第一个出现（从头到尾遍历双端队列）。如果双端队列不包含该元素，则保持不变。更正式地说，删除第一个使得o.equals(e)的元素e（如果存在这样的元素）。如果此双端队列包含指定的元素，则返回true（或者等效地，如果此双端队列由于调用而更改，则返回true）。
      指定由：
      removeFirstOccurrence 在接口 Deque<E>
      参数：
      o - 如果存在，则从此双端队列中删除的元素
      返回：
      如果双端队列包含指定的元素，则返回true

    • removeLastOccurrence

      public boolean removeLastOccurrence(Object o)
      从此双端队列中删除指定元素的最后一个出现（从头到尾遍历双端队列）。如果双端队列不包含该元素，则保持不变。更正式地说，删除最后一个使得o.equals(e)的元素e（如果存在这样的元素）。如果此双端队列包含指定的元素，则返回true（或者等效地，如果此双端队列由于调用而更改，则返回true）。
      指定由：
      removeLastOccurrence 在接口 Deque<E>
      参数：
      o - 如果存在，则从此双端队列中删除的元素
      返回：
      如果双端队列包含指定的元素，则返回true

    • add

      public boolean add(E e)
      将指定的元素插入到此双端队列的末尾。

      此方法等效于addLast(E)。

      指定由：
      add 在接口 Collection<E>
      指定由：
      add 在接口 Deque<E>
      指定由：
      add 在接口 Queue<E>
      覆盖：
      add 在类 AbstractCollection<E>
      参数：
      e - 要添加的元素
      返回：
      true（如Collection.add(E)指定的）
      抛出：
      NullPointerException - 如果指定的元素为null

    • offer

      public boolean offer(E e)
      将指定的元素插入到此双端队列的末尾。

      此方法等效于offerLast(E)。

      指定由：
      offer 在接口 Deque<E>
      指定由：
      offer 在接口 Queue<E>
      参数：
      e - 要添加的元素
      返回：
      true（如Queue.offer(E)指定的）
      抛出：
      NullPointerException - 如果指定的元素为null

    • remove

      public E remove()
      检索并删除由此双端队列表示的队列的头部。此方法与poll()的区别仅在于，如果此双端队列为空，则会抛出异常。

      此方法等效于removeFirst()。

      指定由：
      remove 在接口 Deque<E>
      指定由：
      remove 在接口 Queue<E>
      返回：
      此双端队列表示的队列的头部
      抛出：
      NoSuchElementException - 如果此双端队列为空

    • poll

      public E poll()
      检索并删除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），如果此双端队列为空则返回null。

      此方法等效于pollFirst()。

      指定由：
      poll 在接口 Deque<E>
      指定由：
      poll 在接口 Queue<E>
      返回：
      此双端队列表示的队列的头部，如果此双端队列为空则返回null

    • element

      public E element()
      检索但不删除由此双端队列表示的队列的头部。此方法与peek的区别仅在于，如果此双端队列为空，则会抛出异常。

      此方法等效于getFirst()。

      指定由：
      element 在接口 Deque<E>
      指定由：
      element 在接口 Queue<E>
      返回：
      此双端队列表示的队列的头部
      抛出：
      NoSuchElementException - 如果此双端队列为空

    • peek

      public E peek()
      检索但不删除由此双端队列表示的队列的头部，如果此双端队列为空则返回null。

      此方法等效于peekFirst()。

      指定由：
      peek 在接口 Deque<E>
      指定由：
      peek 在接口 Queue<E>
      返回：
      此双端队列表示的队列的头部，如果此双端队列为空则返回null

    • push

      public void push(E e)
      将一个元素推入由此双端队列表示的堆栈。换句话说，在此双端队列的前面插入元素。

      此方法等效于addFirst(E)。

      指定由：
      push 在接口 Deque<E>
      参数：
      e - 要推入的元素
      抛出：
      NullPointerException - 如果指定的元素为null

    • pop

      public E pop()
      从由此双端队列表示的堆栈中弹出一个元素。换句话说，删除并返回此双端队列的第一个元素。

      此方法等效于removeFirst()。

      指定由：
      pop 在接口 Deque<E>
      返回：
      此双端队列的前端（即由此双端队列表示的堆栈的顶部）的元素
      抛出：
      NoSuchElementException - 如果此双端队列为空

    • size

      public int size()
      返回此双端队列中的元素数量。
      指定由：
      size 在接口 Collection<E>
      指定由：
      size 在接口 Deque<E>
      返回：
      此双端队列中的元素数量

    • isEmpty

      public boolean isEmpty()
      如果此双端队列不包含任何元素，则返回true。
      指定者：
      在接口中：isEmpty Collection<E>
      覆盖：
      在类中：isEmpty AbstractCollection<E>
      返回：
      如果此双端队列不包含任何元素，则返回true

    • iterator

      public Iterator<E> iterator()
      返回此双端队列中元素的迭代器。元素将按照从第一个（头部）到最后一个（尾部）的顺序排序。这与通过连续调用remove()或通过连续调用pop()来出队元素的顺序相同。
      指定者：
      在接口中：iterator Collection<E>
      指定者：
      在接口中：iterator Deque<E>
      指定者：
      在接口中：iterator Iterable<E>
      指定者：
      在类中：iterator AbstractCollection<E>
      返回：
      返回此双端队列中元素的迭代器

    • descendingIterator

      public Iterator<E> descendingIterator()
      从接口复制的描述： Deque
      以逆序顺序返回此双端队列中元素的迭代器。元素将按照从最后一个（尾部）到第一个（头部）的顺序返回。
      指定者：
      在接口中：descendingIterator Deque<E>
      返回：
      以逆序顺序返回此双端队列中元素的迭代器

    • spliterator

      public Spliterator<E> spliterator()
      创建一个延迟绑定和快速失败的Spliterator，用于遍历此双端队列中的元素。

      Spliterator报告Spliterator.SIZED、Spliterator.SUBSIZED、Spliterator.ORDERED和Spliterator.NONNULL。重写实现应该记录额外特征值的报告。

      指定者：
      在接口中：spliterator Collection<E>
      指定者：
      在接口中：spliterator Iterable<E>
      返回：
      返回此双端队列中元素的Spliterator
      自1.8起：
      1.8

    • forEach

      public void forEach(Consumer<? super E> action)
      从接口复制的描述： Iterable
      对Iterable的每个元素执行给定操作，直到所有元素都已处理完或操作引发异常。如果指定了顺序，则按迭代顺序执行操作。操作引发的异常将传递给调用者。

      如果操作执行会修改元素的底层源，则此方法的行为是未指定的，除非覆盖类已指定并发修改策略。

      指定者：
      在接口中：forEach Iterable<E>
      参数：
      action - 要对每个元素执行的操作
      抛出：
      NullPointerException - 如果指定的操作为null

    • removeIf

      public boolean removeIf(Predicate<? super E> filter)
      从接口复制的描述： Collection
      删除满足给定谓词的此集合的所有元素。在迭代期间抛出的错误或运行时异常或由谓词抛出的异常将传递给调用者。
      指定者：
      在接口中：removeIf Collection<E>
      参数：
      filter - 返回true以删除元素的谓词
      返回：
      如果删除了任何元素，则返回true
      抛出：
      NullPointerException - 如果指定的过滤器为null

    • removeAll

      public boolean removeAll(Collection<?> c)
      从类复制的描述： AbstractCollection
      删除此集合中与指定集合中包含的所有元素相同的所有元素（可选操作）。调用此方法后，此集合将不包含与指定集合中的元素相同的任何元素。
      指定者：
      在接口中：removeAll Collection<E>
      覆盖：
      在类中：removeAll AbstractCollection<E>
      参数：
      c - 包含要从此集合中删除的元素的集合
      返回：
      如果此集合由于调用而更改，则返回true
      抛出：
      NullPointerException - 如果此集合包含一个或多个null元素，而指定的集合不支持null元素（可选），或者指定的集合为null
      参见：

    • retainAll

      public boolean retainAll(Collection<?> c)
      从类复制的描述： AbstractCollection
      仅保留此集合中包含在指定集合中的元素（可选操作）。换句话说，从此集合中删除不包含在指定集合中的所有元素。
      指定者：
      在接口中：retainAll Collection<E>
      覆盖：
      在类中：retainAll AbstractCollection<E>
      参数：
      c - 包含要在此集合中保留的元素的集合
      返回：
      如果此集合由于调用而更改，则返回true
      抛出：
      NullPointerException - 如果此集合包含一个或多个null元素，而指定的集合不允许null元素（可选），或者指定的集合为null
      参见：

    • contains

      public boolean contains(Object o)
      如果此双端队列包含指定的元素，则返回true。更正式地说，仅当此双端队列包含至少一个元素e，使得o.equals(e)时返回true。
      指定者:
      contains 在接口 Collection<E>中
      指定者:
      contains 在接口 Deque<E>中
      覆盖:
      contains 在类 AbstractCollection<E>中
      参数:
      o - 要在此双端队列中检查包含性的对象
      返回值:
      如果此双端队列包含指定元素，则返回true

    • remove

      public boolean remove(Object o)
      从此双端队列中删除指定元素的单个实例。如果双端队列不包含该元素，则保持不变。更正式地说，删除第一个元素e，使得o.equals(e)（如果存在这样的元素）。如果此双端队列包含指定元素，则返回true（或者等效地，如果此双端队列由于调用而更改）。

      此方法等效于removeFirstOccurrence(Object)。

      指定者:
      remove 在接口 Collection<E>中
      指定者:
      remove 在接口 Deque<E>中
      覆盖:
      remove 在类 AbstractCollection<E>中
      参数:
      o - 如果存在，则从此双端队列中删除的元素
      返回值:
      如果此双端队列包含指定元素，则返回true

    • clear

      public void clear()
      从此双端队列中删除所有元素。此调用返回后，双端队列将为空。
      指定者:
      clear 在接口 Collection<E>中
      覆盖:
      clear 在类 AbstractCollection<E>中

    • toArray

      public Object[] toArray()
      返回一个包含此双端队列中所有元素的数组，按正确顺序排列（从第一个元素到最后一个元素）。

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

      此方法充当基于数组和基于集合的API之间的桥梁。

      指定者:
      toArray 在接口 Collection<E>中
      覆盖:
      toArray 在类 AbstractCollection<E>中
      返回值:
      包含此双端队列中所有元素的数组

    • toArray

      public <T> T[] toArray(T[] a)
      返回一个包含此双端队列中所有元素的数组，按正确顺序排列（从第一个元素到最后一个元素）；返回数组的运行时类型是指定数组的类型。如果双端队列适合指定数组，则将其返回。否则，将使用指定数组的运行时类型和此双端队列的大小分配一个新数组。

      如果此双端队列适合指定数组且有多余空间（即，数组的元素比此双端队列多），则在双端队列末尾之后的数组元素将设置为null。

      与toArray()方法一样，此方法充当基于数组和基于集合的API之间的桥梁。此外，此方法允许精确控制输出数组的运行时类型，并且在某些情况下可用于节省分配成本。

      假设x是已知仅包含字符串的双端队列。可以使用以下代码将双端队列转储到新分配的String数组中：

       String[] y = x.toArray(new String[0]);
      请注意，toArray(new Object[0])在功能上与toArray()相同。
      指定者:
      toArray 在接口 Collection<E>中
      覆盖:
      toArray 在类 AbstractCollection<E>中
      类型参数:
      T - 包含集合的数组的组件类型
      参数:
      a - 如果足够大，则将双端队列的元素存储在其中的数组；否则，将为此目的分配相同运行时类型的新数组
      返回值:
      包含此双端队列中所有元素的数组
      抛出:
      ArrayStoreException - 如果指定数组的运行时类型不是此双端队列中每个元素的运行时类型的超类型
      NullPointerException - 如果指定数组为null

    • clone

      public ArrayDeque<E> clone()
      返回此双端队列的副本。
      覆盖:
      clone 在类 Object中
      返回值:
      此双端队列的副本
      参见: