モジュール java.base
パッケージ java.util

インタフェースDeque<E>

型パラメータ:
E - この両端キューに保持されている要素の型
すべてのスーパー・インタフェース:
Collection<E>, Iterable<E>, Queue<E>
既知のすべてのサブインタフェース:
BlockingDeque<E>
既知のすべての実装クラス:
ArrayDeque, ConcurrentLinkedDeque, LinkedBlockingDeque, LinkedList
public interface Deque<E> extends Queue<E>
両端で要素の挿入および削除をサポートする線形コレクションです。 「deque」という名前は、「double ended queue」(両端キュー)の省略形であり、通常は「デック」と発音されます。 Dequeのほとんどの実装では格納可能な要素の数に固定された制限はありませんが、このインタフェースでは、容量が制限された両端キューと、固定サイズ制限のない両端キューをサポートしています。

このインタフェースは、両端キューの両端にある要素にアクセスするメソッドを定義します。 要素を挿入、削除、および検査するためのメソッドが提供されています。 これらのメソッドにはそれぞれ、2つの形式があります。1つは操作が失敗したときに例外をスローし、もう1つは特殊な値(操作に応じてnullまたはfalseのいずれか)を返します。 後者の形式の挿入操作は、容量の制限されたDeque実装用として特別に設計されたものですが、ほとんどの実装では挿入操作は失敗できません。

前述の12個のメソッドについて次の表にまとめます。

Dequeメソッドのサマリー
最初の要素(先頭) 最後の要素(末尾)
例外のスロー 特殊な値 例外のスロー 特殊な値
挿入 addFirst(e) offerFirst(e) addLast(e) offerLast(e)
削除 removeFirst() pollFirst() removeLast() pollLast()
調査 getFirst() peekFirst() getLast() peekLast()

このインタフェースは、Queueインタフェースを拡張します。 両端キューがキューとして使用される場合、FIFO (先入れ先出し)動作になります。 要素は両端キューの末尾に追加され、先頭から削除されます。 Queueインタフェースから継承されたメソッドは、次の表に示すようにDequeメソッドと完全に等価です。

QueueメソッドとDequeメソッドの比較
Queueメソッド 等価なDequeメソッド
add(e) addLast(e)
offer(e) offerLast(e)
remove() removeFirst()
poll() pollFirst()
element() getFirst()
peek() peekFirst()

両端キューは、LIFO (後入れ先出し)スタックとして使用することもできます。 .従来のStackクラスよりもこのインタフェースを優先して使用してください。 両端キューがスタックとして使用される場合、両端キューの先頭から要素のプッシュとポップが行われます。 スタック・メソッドは、次の表に示すようにDequeメソッドと同等です。

StackメソッドとDequeメソッドの比較
Stackメソッド 等価なDequeメソッド
push(e) addFirst(e)
pop() removeFirst()
peek() getFirst()

両端キューがキューまたはスタックとして使用される場合、peekメソッドも同様に機能します。どちらの場合も、要素は両端キューの先頭から取り出されます。

このインタフェースには、内部要素を削除するための2つのメソッドremoveFirstOccurrenceおよびremoveLastOccurrenceがあります。

Listインタフェースとは異なり、このインタフェースはインデックスで要素にアクセスするためのサポートを提供しません。

Deque実装では、null要素の挿入を禁止することが厳密には必要ありませんが、禁止することを強くお薦めします。 null要素が許可されたDeque実装のユーザーは、nullを挿入する機能を利用しないことを強くお薦めします。 これは、nullが両端キューが空であることを示すさまざまなメソッドによって特殊な戻り値として使用されるためです。

通常、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をスローします。
    E
    remove()
    この両端キューによって表されるキューの先頭(つまり、この両端キューの最初の要素)を取得して削除します。
    boolean
    remove(Object o)
    指定された要素のうち最初に出現したものを、この両端キューから削除します。
    E
    removeFirst()
    この両端キューの最初の要素を取得して削除します。
    boolean
    removeFirstOccurrence(Object o)
    指定された要素のうち最初に出現したものを、この両端キューから削除します。
    E
    removeLast()
    この両端キューの最後の要素を取得して削除します。
    boolean
    removeLastOccurrence(Object o)
    指定された要素のうち最後に出現したものを、この両端キューから削除します。
    int
    size()
    この両端キュー内の要素の数を返します。

    インタフェース java.util.Collectionで宣言されたメソッド

    clear, containsAll, equals, hashCode, isEmpty, parallelStream, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray, toArray

    インタフェース java.lang.Iterableで宣言されたメソッド

    forEach

  • メソッドの詳細

    • 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)
      指定された要素のうち最初に出現したものを、この両端キューから削除します。 その要素が両端キューにない場合、変更はありません。 より正式には、Objects.equals(o, e) (そのような要素が存在する場合)のような最初の要素eを削除します。 指定された要素がこの両端キューに含まれていた場合(すなわち、呼出しの結果としてこの両端キューが変更された場合)はtrueを返します。
      パラメータ:
      o - この両端キューから削除される要素(その要素が存在する場合)
      戻り値:
      この呼出しの結果として要素が削除された場合はtrue
      例外:
      ClassCastException - 指定された要素のクラスが、この両端キューと互換でない場合(オプション)
      NullPointerException - 指定された要素がnullで、この両端キューがnull要素を許可しない場合(オプション)

    • removeLastOccurrence

      boolean removeLastOccurrence(Object o)
      指定された要素のうち最後に出現したものを、この両端キューから削除します。 その要素が両端キューにない場合、変更はありません。 より正式には、Objects.equals(o, e) (そのような要素が存在する場合)のような最後の要素eを削除します。 指定された要素がこの両端キューに含まれていた場合(すなわち、呼出しの結果としてこの両端キューが変更された場合)はtrueを返します。
      パラメータ:
      o - この両端キューから削除される要素(その要素が存在する場合)
      戻り値:
      この呼出しの結果として要素が削除された場合はtrue
      例外:
      ClassCastException - 指定された要素のクラスが、この両端キューと互換でない場合(オプション)
      NullPointerException - 指定された要素がnullで、この両端キューがnull要素を許可しない場合(オプション)

    • add

      boolean add(E e)
      指定された要素を、この両端キューで表されるキュー(つまり、この両端キューの末尾)に、容量制限に違反することなしにすぐに挿入できる場合には、そうします。成功した場合はtrueを返し、使用可能な空き領域がその時点で存在しない場合はIllegalStateExceptionをスローします。 容量制限のある両端キューを使用する場合、通常はofferを使用することをお薦めします。

      このメソッドは、addLast(E)と同等です。

      定義:
      add、インタフェースCollection<E>
      定義:
      add、インタフェースQueue<E>
      パラメータ:
      e - 追加する要素
      戻り値:
      true (Collection.add(E)で指定されているとおり)
      例外:
      IllegalStateException - 容量制限のために、この時点で要素を追加できない場合
      ClassCastException - 指定された要素のクラスが原因で、この両端キューにその要素を追加できない場合
      NullPointerException - 指定された要素がnullで、この両端キューがnull要素を許可しない場合
      IllegalArgumentException - 指定された要素のあるプロパティが原因で、この両端キューにその要素を追加できない場合

    • offer

      boolean offer(E e)
      指定された要素を、この両端キューで表されるキュー(つまり、この両端キューの末尾)に、容量制限に違反することなしにすぐに挿入できる場合には、そうします。成功した場合はtrueを返し、使用可能な空き領域がその時点で存在しない場合はfalseを返します。 容量制限のある両端キューを使用する場合、通常は、要素の挿入に失敗した場合に例外をスローするのみのadd(E)メソッドよりもこのメソッドを使用することをお薦めします。

      このメソッドは、offerLast(E)と同等です。

      定義:
      offer、インタフェースQueue<E>
      パラメータ:
      e - 追加する要素
      戻り値:
      要素がこの両端キューに追加された場合はtrue、それ以外の場合はfalse
      例外:
      ClassCastException - 指定された要素のクラスが原因で、この両端キューにその要素を追加できない場合
      NullPointerException - 指定された要素がnullで、この両端キューがnull要素を許可しない場合
      IllegalArgumentException - 指定された要素のあるプロパティが原因で、この両端キューにその要素を追加できない場合

    • remove

      E remove()
      この両端キューによって表されるキューの先頭(つまり、この両端キューの最初の要素)を取得して削除します。 このメソッドは、両端キューが空の場合に例外をスローする点のみがpoll()メソッドと異なります。

      このメソッドは、removeFirst()と同等です。

      定義:
      remove、インタフェースQueue<E>
      戻り値:
      この両端キューで表されるキューの先頭
      例外:
      NoSuchElementException - この両端キューが空の場合

    • poll

      E poll()
      この両端キューによって表されるキューの先頭(つまり、この両端キューの最初の要素)を取得および削除します。両端キューが空の場合は、nullを返します。

      このメソッドは、pollFirst()と同等です。

      定義:
      poll、インタフェースQueue<E>
      戻り値:
      この両端キューの最初の要素。この両端キューが空の場合はnull

    • element

      E element()
      この両端キューによって表されるキューの先頭(つまり、この両端キューの最初の要素)を取得しますが、削除しません。 このメソッドは、両端キューが空の場合に例外をスローする点のみがpeekメソッドと異なります。

      このメソッドは、getFirst()と同等です。

      定義:
      element、インタフェースQueue<E>
      戻り値:
      この両端キューで表されるキューの先頭
      例外:
      NoSuchElementException - この両端キューが空の場合

    • peek

      E peek()
      この両端キューによって表されるキューの先頭(つまり、この両端キューの最初の要素)を取得しますが、削除しません。両端キューが空の場合は、nullを返します。

      このメソッドは、peekFirst()と同等です。

      定義:
      peek、インタフェースQueue<E>
      戻り値:
      この両端キューで表されるキューの先頭。この両端キューが空の場合はnull

    • addAll

      boolean addAll(Collection<? extends E> c)
      指定されたコレクション内のすべての要素を、この両端キューの最後に、コレクション・イテレータによって返される順序で、それぞれaddLast(E)を呼び出すかのように追加します。

      容量制限付きの両端キューを使用する場合は、各要素ごとにofferを別々に呼び出す方が一般的に適しています。

      要素の追加中に例外が発生すると、関連する例外がスローされたときに要素の一部だけが正常に追加されることがあります。

      定義:
      addAll、インタフェースCollection<E>
      パラメータ:
      c - この両端キューに挿入される要素
      戻り値:
      この呼出しの結果、この両端キューが変更された場合はtrue
      例外:
      IllegalStateException - 挿入制限のため、この時点で一部の要素を追加できない場合
      ClassCastException - 指定されたコレクションの要素のクラスがこの両端キューに追加できない場合
      NullPointerException - 指定されたコレクションがnull要素を含み、この両端キューがnull要素を許可しない場合、または指定されたコレクションがnullの場合
      IllegalArgumentException - 指定されたコレクションの要素のいくつかのプロパティが、この両端キューに追加できない場合
      関連項目:

    • push

      void push(E e)
      容量制限に違反することなしに要素をこの両端キューで表されるスタック(つまり、この両端キューの先頭)にすぐにプッシュできる場合は、そうします。使用可能な空き領域がその時点で存在しない場合はIllegalStateExceptionをスローします。

      このメソッドは、addFirst(E)と同等です。

      パラメータ:
      e - プッシュする要素
      例外:
      IllegalStateException - 容量制限のために、この時点で要素を追加できない場合
      ClassCastException - 指定された要素のクラスが原因で、この両端キューにその要素を追加できない場合
      NullPointerException - 指定された要素がnullで、この両端キューがnull要素を許可しない場合
      IllegalArgumentException - 指定された要素のあるプロパティが原因で、この両端キューにその要素を追加できない場合

    • pop

      E pop()
      この両端キューで表されるスタックに要素をポップします。 つまり、この両端キューの最初の要素を削除して返します。

      このメソッドは、removeFirst()と同等です。

      戻り値:
      この両端キューの先頭の要素(この両端キューによって表されるスタックの上部)
      例外:
      NoSuchElementException - この両端キューが空の場合

    • remove

      boolean remove(Object o)
      指定された要素のうち最初に出現したものを、この両端キューから削除します。 その要素が両端キューにない場合、変更はありません。 より正式には、Objects.equals(o, e) (そのような要素が存在する場合)のような最初の要素eを削除します。 指定された要素がこの両端キューに含まれていた場合(すなわち、呼出しの結果としてこの両端キューが変更された場合)はtrueを返します。

      このメソッドは、removeFirstOccurrence(Object)と同等です。

      定義:
      remove、インタフェースCollection<E>
      パラメータ:
      o - この両端キューから削除される要素(その要素が存在する場合)
      戻り値:
      この呼出しの結果として要素が削除された場合はtrue
      例外:
      ClassCastException - 指定された要素のクラスが、この両端キューと互換でない場合(オプション)
      NullPointerException - 指定された要素がnullで、この両端キューがnull要素を許可しない場合(オプション)

    • contains

      boolean contains(Object o)
      指定された要素がこの両端キューに含まれている場合にtrueを返します。 より正式には、この両端キューに、Objects.equals(o, e)のような少なくとも1つの要素eが含まれている場合に限り、trueを返します。
      定義:
      contains、インタフェースCollection<E>
      パラメータ:
      o - この両端キューにあるかどうかを調べる要素
      戻り値:
      指定された要素がこの両端キューに含まれている場合はtrue
      例外:
      ClassCastException - 指定された要素のクラスが、この両端キューと互換でない場合(オプション)
      NullPointerException - 指定された要素がnullで、この両端キューがnull要素を許可しない場合(オプション)

    • size

      int size()
      この両端キュー内の要素の数を返します。
      定義:
      size、インタフェースCollection<E>
      戻り値:
      この両端キュー内の要素の数

    • iterator

      Iterator<E> iterator()
      この両端キュー内の要素を適切な順序で反復処理するイテレータを返します。 要素は最初(先頭)から最後(末尾)の順に返されます。
      定義:
      iterator、インタフェースCollection<E>
      定義:
      iterator、インタフェースIterable<E>
      戻り値:
      この両端キュー内の要素を適切な順序で反復処理するイテレータ

    • descendingIterator

      Iterator<E> descendingIterator()
      この両端キュー内の要素を逆順で反復処理するイテレータを返します。 要素は最後(末尾)から最初(先頭)の順に返されます。
      戻り値:
      この両端キュー内の要素を逆順で反復処理するイテレータ