模块  java.base
软件包  java.util

Interface Deque<E>

  • 参数类型
    E - 此双端队列中保留的元素类型
    All Superinterfaces:
    Collection<E> ， Iterable<E> ， Queue<E>
    All Known Subinterfaces:
    BlockingDeque<E>
    所有已知实现类：
    ArrayDeque ， ConcurrentLinkedDeque ， LinkedBlockingDeque ， LinkedList 
    public interface Deque<E>
extends Queue<E>
    线性集合，支持两端插入和移除元素。 名称deque是“双端队列”的缩写，通常发音为“deck”。 大多数Deque实现对它们可能包含的元素数量没有固定限制，但此接口支持容量限制的deques以及没有固定大小限制的deques。

    此接口定义了访问双端队列两端元素的方法。 提供了插入，移除和检查元素的方法。 这些方法中的每一种都以两种形式存在：一种在操作失败时抛出异常，另一种返回特殊值（ null或false ，具体取决于操作）。 后一种形式的插入操作专门设计用于容量限制的Deque实现; 在大多数实现中，插入操作不会失败。

    上述十二种方法总结在下表中：

    Summary of Deque methods First Element (Head) Last Element (Tail) Throws exception Special value Throws exception Special value Insert addFirst(e) offerFirst(e) addLast(e) offerLast(e) Remove removeFirst() pollFirst() removeLast() pollLast() Examine getFirst() peekFirst() getLast() peekLast()

    此接口扩展了Queue接口。 当deque用作队列时，会产生FIFO（先进先出）行为。 元素在双端队列的末尾添加并从头开始删除。 继承自Queue接口的方法与Deque方法完全等效，如下表所示：

    Comparison of Queue and Deque methods Queue Method Equivalent Deque Method add(e) addLast(e) offer(e) offerLast(e) remove() removeFirst() poll() pollFirst() element() getFirst() peek() peekFirst()

    Deques也可以用作LIFO（后进先出）堆栈。 应优先使用此接口，而不是旧版Stack 。 当deque用作堆栈时，元素将从双端队列的开头推出并弹出。 堆栈方法相当于Deque方法，如下表所示：

    Comparison of Stack and Deque methods Stack Method Equivalent Deque Method push(e) addFirst(e) pop() removeFirst() peek() getFirst()

    请注意，当deque用作队列或堆栈时， peek方法同样有效; 在任何一种情况下，元素都是从双端队列的开头绘制的。

    此界面提供了两种删除内部元素的方法， removeFirstOccurrence和removeLastOccurrence 。

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

    虽然严格要求Deque实现禁止插入null元素，但强烈建议他们这样做。 任何用户Deque强烈建议实现，也允许null元素不采取插入空的能力优势。 这是因为null被各种方法用作特殊返回值，以指示deque为空。

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

    此接口是Java Collections Framework的成员。

    从以下版本开始：
    1.6

    • 方法摘要

      所有方法  实例方法 抽象方法 
      变量和类型 方法 描述
      boolean add​(E e)
      将指定的元素插入此双端队列表示的队列中（换句话说，在此双端队列的尾部），如果它是立即可行且不会违反容量限制，返回 true成功时和抛出 IllegalStateException如果当前没有空间可用的。
      boolean addAll​(Collection<? extends E> c)
      在此双端队列的末尾添加指定集合中的所有元素，就像通过在每个 对象上调用 addLast(E)一样 ，按照集合的迭代器返回它们的顺序。
      void addFirst​(E e)
      如果可以在不违反容量限制的情况下立即插入指定元素，则在此双端队列的前面插入指定元素，如果当前没有可用空间，则抛出 IllegalStateException 。
      void addLast​(E e)
      如果可以在不违反容量限制的情况下立即插入指定元素，则在此双端队列的末尾插入指定元素，如果当前没有可用空间，则抛出 IllegalStateException 。
      boolean contains​(Object o)
      如果此双端队列包含指定的元素，则返回 true 。
      Iterator<E> descendingIterator()
      以相反的顺序返回此双端队列中元素的迭代器。
      E element()
      检索但不删除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素）。
      E getFirst()
      检索但不删除此双端队列的第一个元素。
      E getLast()
      检索但不删除此双端队列的最后一个元素。
      Iterator<E> iterator()
      以适当的顺序返回此双端队列中元素的迭代器。
      boolean offer​(E e)
      将指定的元素插入此双端队列表示的队列中（换句话说，在此双端队列的尾部），如果它是立即可行且不会违反容量限制，返回 true在成功和 false如果当前没有空间可用。
      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)
      如果可以在不违反容量限制的情况下立即执行此操作， IllegalStateException到此双端队列表示的堆栈（换句话说，在此双端队列的头部），如果当前没有可用空间则抛出 IllegalStateException 。
      E remove()
      检索并删除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素）。
      boolean remove​(Object o)
      从此双端队列中删除第一次出现的指定元素。
      E removeFirst()
      检索并删除此双端队列的第一个元素。
      boolean removeFirstOccurrence​(Object o)
      从此双端队列中删除第一次出现的指定元素。
      E removeLast()
      检索并删除此双端队列的最后一个元素。
      boolean removeLastOccurrence​(Object o)
      从此双端队列中删除最后一次出现的指定元素。
      int size()
      返回此双端队列中的元素数。

    • 方法详细信息

      • addFirst

        void addFirst​(E e)
        如果可以在不违反容量限制的情况下立即插入指定元素，则在此双端队列的前面插入指定元素，如果当前没有可用空间，则抛出IllegalStateException 。 当使用容量限制的双端队列时，通常优选使用方法offerFirst(E) 。
        参数
        e - 要添加的元素
        异常
        IllegalStateException - 如果由于容量限制，此时无法添加元素
        ClassCastException - 如果指定元素的类阻止将其添加到此双端队列中
        NullPointerException - 如果指定的元素为null且此双端队列不允许null元素
        IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

      • addLast

        void addLast​(E e)
        如果可以在不违反容量限制的情况下立即插入指定元素，则在此双端队列的末尾插入指定元素，如果当前没有可用空间，则抛出IllegalStateException 。 当使用容量限制的双端队列时，通常优选使用方法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)
        从此双端队列中删除第一次出现的指定元素。 如果双端队列不包含该元素，则不会更改。 更正式地，删除第一个元素e ，使得Objects.equals(o, e) （如果存在这样的元素）。 如果此双端队列包含指定的元素，则返回true （或等效地，如果此双端队列因调用而更改）。
        参数
        o - 要从此双端队列中删除的元素（如果存在）
        结果
        true如果由于此调用而删除了某个元素
        异常
        ClassCastException - 如果指定元素的类与此双端队列不兼容（ optional ）
        NullPointerException - 如果指定的元素为null且此双端队列不允许null元素（ optional ）

      • removeLastOccurrence

        boolean removeLastOccurrence​(Object o)
        从此双端队列中删除最后一次出现的指定元素。 如果双端队列不包含该元素，则不会更改。 更正式地，删除最后一个元素e ，使得Objects.equals(o, e) （如果存在这样的元素）。 如果此双端队列包含指定的元素，则返回true （或等效地，如果此双端队列因调用而更改）。
        参数
        o - 要从此双端队列中删除的元素（如果存在）
        结果
        true如果由于此调用而删除了一个元素
        异常
        ClassCastException - 如果指定元素的类与此双端队列不兼容（ optional ）
        NullPointerException - 如果指定的元素为null且此双端队列不允许null元素（ optional ）

      • add

        boolean add​(E e)
        将指定的元素插入此双端队列表示的队列中（换句话说，在此双端队列的尾部），如果它是立即可行且不会违反容量限制，返回true成功时和抛出IllegalStateException如果当前没有空间可用的。 当使用容量限制的双端队列时，通常优选使用offer 。

        此方法相当于addLast(E) 。

        Specified by:
        add在界面 Collection<E>
        Specified by:
        add in interface Queue<E>
        参数
        e - 要添加的元素
        结果
        true （由 Collection.add(E)指定）
        异常
        IllegalStateException - 如果由于容量限制，此时无法添加元素
        ClassCastException - 如果指定元素的类阻止将其添加到此双端队列中
        NullPointerException - 如果指定的元素为null且此双端队列不允许null元素
        IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列

      • offer

        boolean offer​(E e)
        将指定的元素插入此双端队列表示的队列中（换句话说，在此双端队列的尾部），如果它是立即可行且不会违反容量限制，返回true在成功和false如果当前没有空间可用。 使用容量限制的双端队列时，此方法通常优于add(E)方法，该方法只能通过抛出异常来插入元素。

        此方法相当于offerLast(E) 。

        Specified by:
        offer在界面 Queue<E>
        参数
        e - 要添加的元素
        结果
        true如果元素已添加到此双端队列， false
        异常
        ClassCastException - 如果指定元素的类阻止将其添加到此双端队列中
        NullPointerException - 如果指定的元素为null且此双端队列不允许null元素
        IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

      • remove

        E remove()
        检索并删除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素）。 此方法与poll()的不同之处仅在于，如果此双端队列为空，则会抛出异常。

        此方法相当于removeFirst() 。

        Specified by:
        remove在界面 Queue<E>
        结果
        这个双端队列所代表的队列的头部
        异常
        NoSuchElementException - 如果此双端队列是空的

      • poll

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

        此方法相当于pollFirst() 。

        Specified by:
        poll在界面 Queue<E>
        结果
        此双端队列的第一个元素，如果此双端队列为空， null

      • element

        E element()
        检索但不删除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素）。 此方法与peek的不同之处仅在于，如果此双端队列为空，则会抛出异常。

        此方法相当于getFirst() 。

        Specified by:
        element在界面 Queue<E>
        结果
        这个双端队列所代表的队列的头部
        异常
        NoSuchElementException - 如果此双端队列是空的

      • peek

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

        此方法相当于peekFirst() 。

        Specified by:
        peek在接口 Queue<E>
        结果
        此双端队列表示队列的头部，如果此双端队列为空， null

      • addAll

        boolean addAll​(Collection<? extends E> c)
        在此双端队列的末尾添加指定集合中的所有元素，就好像通过在每个双端子上调用addLast(E)一样 ，按照集合的迭代器返回它们的顺序。

        使用容量限制的双端队列时，通常最好分别在每个元素上调用offer 。

        尝试添加元素时遇到的异常可能导致在抛出关联的异常时仅成功添加了一些元素。

        Specified by:
        addAll in interface Collection<E>
        参数
        c - 要插入此双端队列的元素
        结果
        true如果此deque因呼叫而改变
        异常
        IllegalStateException - 如果不是因为插入限制，此时可以添加所有元素
        ClassCastException - 如果指定集合的元素的类阻止将其添加到此双端队列中
        NullPointerException - 如果指定的集合包含null元素且此双端队列不允许null元素，或者指定的集合为null
        IllegalArgumentException - 如果指定集合的元素的某些属性阻止将其添加到此双端队列中
        另请参见：
        Collection.add(Object)

      • push

        void push​(E e)
        如果可以在不违反容量限制的情况下立即执行此操作， IllegalStateException到此双端队列表示的堆栈（换句话说，在此双端队列的头部），如果当前没有可用空间则抛出IllegalStateException 。

        此方法相当于addFirst(E) 。

        参数
        e - 要推送的元素
        异常
        IllegalStateException - 如果由于容量限制而无法在此时添加元素
        ClassCastException - 如果指定元素的类阻止将其添加到此双端队列
        NullPointerException - 如果指定的元素为null且此双端队列不允许null元素
        IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列

      • pop

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

        此方法相当于removeFirst() 。

        结果
        此双端队列前面的元素（此双端队列表示的堆栈顶部）
        异常
        NoSuchElementException - 如果此双端队列是空的

      • remove

        boolean remove​(Object o)
        从此双端队列中删除第一次出现的指定元素。 如果双端队列不包含该元素，则不会更改。 更正式地，删除第一个元素e ，使得Objects.equals(o, e) （如果存在这样的元素）。 如果此双端队列包含指定的元素，则返回true （或等效地，如果此双端队列因调用而更改）。

        此方法相当于removeFirstOccurrence(Object) 。

        Specified by:
        remove在界面 Collection<E>
        参数
        o - 要从此双端队列中删除的元素（如果存在）
        结果
        true如果由于此调用而删除了某个元素
        异常
        ClassCastException - 如果指定元素的类与此双端队列不兼容（ optional ）
        NullPointerException - 如果指定的元素为null且此双端队列不允许null元素（ optional ）

      • contains

        boolean contains​(Object o)
        如果此双端队列包含指定的元素，则返回true 。 更正式地，当且仅当此双端队列包含至少一个元素e时才返回true Objects.equals(o, e) 。
        Specified by:
        contains在界面 Collection<E>
        参数
        o - 要测试其在此双端队列中的存在的元素
        结果
        true如果此双端队列包含指定的元素
        异常
        ClassCastException - 如果指定元素的类与此双端队列不兼容（ optional ）
        NullPointerException - 如果指定的元素为null且此双端队列不允许null元素（ optional ）

      • size

        int size()
        返回此双端队列中的元素数。
        Specified by:
        size在界面 Collection<E>
        结果
        此双端队列中的元素数量

      • iterator

        Iterator<E> iterator()
        以适当的顺序返回此双端队列中元素的迭代器。 元素将从第一个（头部）到最后一个（尾部）按顺序返回。
        Specified by:
        iterator在界面 Collection<E>
        Specified by:
        iterator在界面 Iterable<E>
        结果
        以适当的顺序在此双端队列中的元素上的迭代器

      • descendingIterator

        Iterator<E> descendingIterator()
        以相反的顺序返回此双端队列中元素的迭代器。 元素将按从最后（尾部）到第一个（头部）的顺序返回。
        结果
        an iterator over the elements in this deque in reverse sequence