模块 java.base
包 java.util

类 ArrayDeque<E>

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

大多数 ArrayDeque 操作以摊销常数时间运行。例外包括 remove 、 removeFirstOccurrence 、 removeLastOccurrence 、 contains 、 iterator.remove() 和批量操作，所有这些操作都在线性时间内运行。

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

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

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

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

自从：
1.6
参见：

  • 构造方法总结

    构造方法
    构造方法
    描述
    ArrayDeque()
    构造一个空数组双端队列，其初始容量足以容纳 16 个元素。
    ArrayDeque(int numElements)
    构造一个空数组双端队列，其初始容量足以容纳指定数量的元素。
    ArrayDeque(Collection<? extends E> c)
    构造一个包含指定集合元素的双端队列，按照集合迭代器返回元素的顺序。

  • 方法总结

    修饰符和类型
    方法
    描述
    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()
    在此双端队列中的元素上创建 late-binding 和 fail-fast Spliterator 。
    Object[]
    toArray()
    以正确的顺序（从第一个元素到最后一个元素）返回包含此双端队列中所有元素的数组。
    <T> T[]
    toArray(T[] a)
    以正确的顺序（从第一个元素到最后一个元素）返回一个包含此双端队列中所有元素的数组；返回数组的运行时类型是指定数组的类型。

    在类 java.util.AbstractCollection 中声明的方法

    containsAll, toString

    在类 java.lang.Object 中声明的方法

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

    在接口 java.util.Collection 中声明的方法

    containsAll, equals, hashCode, parallelStream, stream, toArray

  • 构造方法详细信息

    • ArrayDeque

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

    • ArrayDeque

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

    • ArrayDeque

      public ArrayDeque(Collection <? extends E > c)
      构造一个包含指定集合元素的双端队列，按照集合迭代器返回元素的顺序。 （集合的迭代器返回的第一个元素成为第一个元素，或者正面双端队列的。）
      参数：
      c - 其元素要放入双端队列的集合
      抛出：
      NullPointerException - 如果指定的集合为空

  • 方法详情

    • addFirst

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

    • addLast

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

      此方法等效于 add(E) 。

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

    • addAll

      public boolean addAll(Collection <? extends E > c)
      将指定集合中的所有元素添加到此双端队列的末尾，就像对每个元素调用 addLast(E) 一样，按照集合的迭代器返回它们的顺序。
      指定者：
      addAll 在接口 Collection<E> 中
      指定者：
      addAll 在接口 Deque<E> 中
      重写：
      addAll 在类 AbstractCollection<E> 中
      参数：
      c - 要插入到此双端队列中的元素
      返回：
      true 如果此双端队列因调用而改变
      抛出：
      NullPointerException - 如果指定的集合或其任何元素为空
      参见：

    • offerFirst

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

    • offerLast

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

    • removeFirst

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

    • removeLast

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

    • getLast

      public E  getLast()
      从接口 Deque 复制的描述
      检索但不删除此双端队列的最后一个元素。此方法与 peekLast 的不同之处仅在于，如果此双端队列为空，它会抛出异常。
      指定者：
      getLast 在接口 Deque<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)
      移除此双端队列中第一次出现的指定元素（从头到尾遍历双端队列时）。如果双端队列不包含该元素，则它不变。更正式地说，删除第一个元素 e 这样 o.equals(e) （如果存在这样的元素）。如果此双端队列包含指定元素，则返回 true（或者等效地，如果此双端队列因调用而更改）。
      指定者：
      removeFirstOccurrence 在接口 Deque<E> 中
      参数：
      o - 要从此双端队列中删除的元素（如果存在）
      返回：
      true 如果双端队列包含指定的元素

    • removeLastOccurrence

      public boolean removeLastOccurrence(Object  o)
      删除此双端队列中最后一次出现的指定元素（从头到尾遍历双端队列时）。如果双端队列不包含该元素，则它不变。更正式地说，删除最后一个元素 e 这样 o.equals(e) （如果存在这样的元素）。如果此双端队列包含指定元素，则返回 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 - 如果指定元素为空

    • offer

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

      此方法等效于 offerLast(E) 。

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

    • 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 - 如果指定元素为空

    • 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()
      在此双端队列中的元素上创建 late-binding 和 fail-fast Spliterator 。

      Spliterator 报告 Spliterator.SIZED 、Spliterator.SUBSIZED 、Spliterator.ORDERED 和 Spliterator.NONNULL 。覆盖实施应记录附加特征值的报告。

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

    • forEach

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

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

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

    • removeIf

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

    • removeAll

      public boolean removeAll(Collection <?> c)
      从类复制的描述：AbstractCollection
      删除此集合的所有也包含在指定集合中的元素（可选操作）。此调用返回后，此集合将不包含与指定集合共有的元素。
      指定者：
      removeAll 在接口 Collection<E> 中
      重写：
      removeAll 在类 AbstractCollection<E> 中
      参数：
      c - 包含要从此集合中删除的元素的集合
      返回：
      true 如果此集合因调用而更改
      抛出：
      NullPointerException - 如果此集合包含一个或多个空元素并且指定的集合不支持空元素 (optional)，或者如果指定的集合为空
      参见：

    • retainAll

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

    • contains

      public boolean contains(Object  o)
      如果此双端队列包含指定元素，则返回 true。更正式地说，返回 true 当且仅当此双端队列包含至少一个元素 e 使得 o.equals(e) 。
      指定者：
      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 - 如果指定数组为空

    • clone

      public ArrayDeque <E > clone()
      返回此双端队列的副本。
      重写：
      clone 在类 Object 中
      返回：
      这个双端队列的副本
      参见：