java.util
インタフェース Deque<E>

型パラメータ:

E - コレクション内に存在する要素の型

すべてのスーパーインタフェース:

Collection<E>, Iterable<E>, Queue<E>

既知のサブインタフェースの一覧:

BlockingDeque<E>

既知の実装クラスの一覧:

ArrayDeque, LinkedBlockingDeque, LinkedList

public interface Deque<E>
extends Queue<E>

両端で要素の挿入および削除をサポートする線形コレクションです。「deque」という名前は、「double ended queue」 (両端キュー) の省略形であり、通常は「デック」と発音されます。ほとんどの Deque 実装では、格納可能な要素の数に固定された制限はありません。ただしこのインタフェースでは、容量が制限された両端キューと、固定サイズ制限のない両端キューがサポートされています。

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

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

	最初の要素 (先頭)		最後の要素 (末尾)
	例外のスロー	特殊な値	例外のスロー	特殊な値
挿入	addFirst(e)	offerFirst(e)	addLast(e)	offerLast(e)
削除	removeFirst()	pollFirst()	removeLast()	pollLast()
検査	getFirst()	peekFirst()	getLast()	peekLast()

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

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

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

Stack メソッド	等価な Deque メソッド
push(e)	addFirst(e)
pop()	removeFirst()
peek()	peekFirst()

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

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

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

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

通常、Deque 実装は要素ベースの equals メソッドおよび hashCode メソッドを定義しませんが、Object クラスからアイデンティティーベースのメソッドを継承します。

このインタフェースは、Java Collections Framework のメンバーです。

導入されたバージョン:

1.6

メソッドの概要

boolean	add(E e) 指定された要素を、この両端キューで表されるキュー (つまり、この両端キューの末尾) に、容量制限に違反することなしにすぐに挿入できる場合には、そうします。
void	addFirst(E e) 容量制限に違反することなく指定された要素をこの両端キューの先頭にすぐに挿入できる場合は、挿入します。
void	addLast(E e) 容量制限に違反することなく指定された要素をこの両端キューの末尾にすぐに挿入できる場合は、そうします。
boolean	contains(Object o) 指定された要素がこの両端キューに含まれている場合に true を返します。
Iterator<E>	descendingIterator() この両端キュー内の要素を逆順で繰り返し処理する反復子を返します。
E	element() この両端キューによって表されるキューの先頭 (つまり、この両端キューの最初の要素) を取得しますが、削除しません。
E	getFirst() この両端キューの最初の要素を取得しますが、削除はしません。
E	getLast() この両端キューの最後の要素を取得しますが、削除はしません。
Iterator<E>	iterator() この両端キュー内の要素を適切な順序で繰り返し処理する反復子を返します。
boolean	offer(E e) 指定された要素を、この両端キューで表されるキュー (つまり、この両端キューの末尾) に、容量制限に違反することなしにすぐに挿入できる場合には、そうします。
boolean	offerFirst(E e) 容量制限に違反しないかぎり、指定された要素をこの両端キューの先頭に挿入します。
boolean	offerLast(E e) 容量制限に違反しないかぎり、指定された要素をこの両端キューの末尾に挿入します。
E	peek() この両端キューによって表されるキューの先頭 (つまり、この両端キューの最初の要素) を取得しますが、削除しません。
E	peekFirst() この両端キューの最初の要素を取得しますが、削除しません。
E	peekLast() この両端キューの最後の要素を取得しますが、削除しません。
E	poll() この両端キューによって表されるキューの先頭 (つまり、この両端キューの最初の要素) を取得および削除します。
E	pollFirst() この両端キューの最初の要素を取得および削除します。
E	pollLast() この両端キューの最後の要素を取得および削除します。
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() この両端キュー内の要素の数を返します。

インタフェース java.util.Collection から継承されたメソッド

addAll, clear, containsAll, equals, hashCode, isEmpty, removeAll, retainAll, toArray, toArray

メソッドの詳細

addFirst

void addFirst(E e)

容量制限に違反することなく指定された要素をこの両端キューの先頭にすぐに挿入できる場合は、挿入します。容量制限のある両端キューを使用する場合、通常は offerFirst(E) メソッドを使用することをお勧めします。

パラメータ:

e - 追加する要素

例外:

IllegalStateException - 容量制限のために要素をその時点で追加できない場合

ClassCastException - 指定された要素のクラスが原因で、この両端キューに要素を追加できない場合

NullPointerException - 指定された要素が null で、この両端キューが null 要素を許容しない場合

IllegalArgumentException - 指定された要素のあるプロパティーが原因で、この両端キューに要素を追加できない場合

addLast

void addLast(E e)

容量制限に違反することなく指定された要素をこの両端キューの末尾にすぐに挿入できる場合は、そうします。容量制限のある両端キューを使用する場合、通常は 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)

指定された要素のうち最初に出現したものを、この両端キューから削除します。その要素が両端キューにない場合、変更はありません。つまり、(o==null ? e==null : o.equals(e)) となる最初の要素 e が存在する場合は、その要素を削除します。指定された要素が両端キュー内にあった場合 (両端キューが呼び出しの結果として変更された場合) は、true を返します。

パラメータ:

o - この両端キューから削除される要素 (その要素が存在する場合)

戻り値:

この呼び出しの結果、要素が削除された場合は true

例外:

ClassCastException - 指定された要素のクラスが、この両端キューと互換でない場合 (省略可能)

NullPointerException - 指定された要素が null であり、この両端キューが null 要素を許可しない場合 (省略可能)

removeLastOccurrence

boolean removeLastOccurrence(Object o)

指定された要素のうち最後に出現したものを、この両端キューから削除します。その要素が両端キューにない場合、変更はありません。つまり、(o==null ? e==null : o.equals(e)) となる最後の要素 e が存在する場合は、その要素を削除します。指定された要素が両端キュー内にあった場合 (両端キューが呼び出しの結果として変更された場合) は、true を返します。

パラメータ:

o - この両端キューから削除される要素 (その要素が存在する場合)

戻り値:

この呼び出しの結果、要素が削除された場合は true

例外:

ClassCastException - 指定された要素のクラスが、この両端キューと互換でない場合 (省略可能)

NullPointerException - 指定された要素が null であり、この両端キューが null 要素を許可しない場合 (省略可能)

add

boolean add(E e)

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

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

定義:

インタフェース Collection<E> 内の add

定義:

インタフェース Queue<E> 内の add

パラメータ:

e - 追加する要素

戻り値:

true (Collection.add(E) で指定されているとおり)

例外:

IllegalStateException - 容量制限のために要素をその時点で追加できない場合

ClassCastException - 指定された要素のクラスが原因で、この両端キューに要素を追加できない場合

NullPointerException - 指定された要素が null で、この両端キューが null 要素を許容しない場合

IllegalArgumentException - 指定された要素のあるプロパティーが原因で、この両端キューに要素を追加できない場合

offer

boolean offer(E e)

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

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

定義:

インタフェース Queue<E> 内の offer

パラメータ:

e - 追加する要素

戻り値:

要素がこの両端キューに追加された場合は true、そうでない場合は false

例外:

ClassCastException - 指定された要素のクラスが原因で、この両端キューに要素を追加できない場合

NullPointerException - 指定された要素が null で、この両端キューが null 要素を許容しない場合

IllegalArgumentException - 指定された要素のあるプロパティーが原因で、この両端キューに要素を追加できない場合

remove

E remove()

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

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

定義:

インタフェース Queue<E> 内の remove

戻り値:

この両端キューで表されるキューの先頭

例外:

NoSuchElementException - 両端キューが空の場合

poll

E poll()

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

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

定義:

インタフェース Queue<E> 内の poll

戻り値:

この両端キューの最初の要素。両端キューが空の場合は null

element

E element()

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

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

定義:

インタフェース Queue<E> 内の element

戻り値:

この両端キューで表されるキューの先頭

例外:

NoSuchElementException - 両端キューが空の場合

peek

E peek()

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

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

定義:

インタフェース Queue<E> 内の peek

戻り値:

この両端キューで表されるキューの先頭。両端キューが空の場合は null

push

void push(E e)

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

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

パラメータ:

e - プッシュする要素

例外:

IllegalStateException - 容量制限のために要素をその時点で追加できない場合

ClassCastException - 指定された要素のクラスが原因で、この両端キューに要素を追加できない場合

NullPointerException - 指定された要素が null で、この両端キューが null 要素を許容しない場合

IllegalArgumentException - 指定された要素のあるプロパティーが原因で、この両端キューに要素を追加できない場合

pop

E pop()

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

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

戻り値:

この両端キューの先頭の要素 (この両端キューによって表されるスタックの上部)

例外:

NoSuchElementException - 両端キューが空の場合

remove

boolean remove(Object o)

指定された要素のうち最初に出現したものを、この両端キューから削除します。その要素が両端キューにない場合、変更はありません。つまり、(o==null ? e==null : o.equals(e)) となる最初の要素 e が存在する場合は、その要素を削除します。指定された要素が両端キュー内にあった場合 (両端キューが呼び出しの結果として変更された場合) は、true を返します。

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

定義:

インタフェース Collection<E> 内の remove

パラメータ:

o - この両端キューから削除される要素 (その要素が存在する場合)

戻り値:

この呼び出しの結果、要素が削除された場合は true

例外:

ClassCastException - 指定された要素のクラスが、この両端キューと互換でない場合 (省略可能)

NullPointerException - 指定された要素が null であり、この両端キューが null 要素を許可しない場合 (省略可能)

contains

boolean contains(Object o)

指定された要素がこの両端キューに含まれている場合に true を返します。つまり、両端キューに、(o==null ? e==null : o.equals(e)) となる要素 e が 1 つ以上含まれている場合にだけ true を返します。

定義:

インタフェース Collection<E> 内の contains

パラメータ:

o - この両端キューにあるかどうかを調べる要素

戻り値:

指定された要素がこの両端キューに含まれている場合は true

例外:

ClassCastException - 指定された要素の型が、この両端キューと互換でない場合 (省略可能)

NullPointerException - 指定された要素が null であり、この両端キューが null 要素を許可しない場合 (省略可能)

size

int size()

この両端キュー内の要素の数を返します。

定義:

インタフェース Collection<E> 内の size

戻り値:

この両端キュー内の要素の数

iterator

Iterator<E> iterator()

この両端キュー内の要素を適切な順序で繰り返し処理する反復子を返します。要素は最初 (先頭) から最後 (末尾) の順に返されます。

定義:

インタフェース Collection<E> 内の iterator

定義:

インタフェース Iterable<E> 内の iterator

戻り値:

この両端キュー内の要素を適切な順序で繰り返し処理する反復子

descendingIterator

Iterator<E> descendingIterator()

この両端キュー内の要素を逆順で繰り返し処理する反復子を返します。要素は最後 (末尾) から最初 (先頭) の順に返されます。

戻り値:

この両端キュー内の要素を逆順で繰り返し処理する反復子