Java : Deque (両端キュー) - API使用例

Deque (Java SE 20 & JDK 20) の使用例まとめです。
だいたいのメソッドを網羅済みです。
API仕様のおともにどうぞ。

概要

両端で要素の挿入および削除をサポートする線形コレクションです。「deque」という名前は、「double ended queue」(両端キュー)の省略形であり、通常は「デック」と発音されます。

クラス構成

Queue は先入れ先出し(FIFO)ですが、Dequeインタフェースでは両端からの挿入・削除が可能です。
主な実装には、ArrayDeque や LinkedList などがあります。

final Deque<String> deque = new ArrayDeque<>();

deque.addLast("aaa");
deque.addLast("bbb");
deque.addLast("ccc");

System.out.println(deque); // [aaa, bbb, ccc]

System.out.println(deque.removeFirst()); // aaa
System.out.println(deque); // [bbb, ccc]

System.out.println(deque.removeFirst()); // bbb
System.out.println(deque); // [ccc]

System.out.println(deque.removeFirst()); // ccc
System.out.println(deque); // []

final Deque<String> deque = new ArrayDeque<>();

deque.addLast("xxx");
deque.addLast("yyy");
deque.addLast("zzz");

System.out.println(deque); // [xxx, yyy, zzz]

System.out.println(deque.removeLast()); // zzz
System.out.println(deque); // [xxx, yyy]

System.out.println(deque.removeLast()); // yyy
System.out.println(deque); // [xxx]

System.out.println(deque.removeLast()); // xxx
System.out.println(deque); // []

メソッド

boolean add (E e)

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

このメソッドは addLast(E e) と同等です。
そちらのAPI使用例をご参照ください。

boolean addAll (Collection<? extends E> c)

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

final Deque<String> deque = new ArrayDeque<>();
System.out.println(deque); // []

System.out.println(deque.addAll(List.of("a1"))); // true
System.out.println(deque); // [a1]

System.out.println(deque.addAll(List.of("b1", "b2"))); // true
System.out.println(deque); // [a1, b1, b2]

System.out.println(deque.addAll(List.of("c1", "c2", "c3"))); // true
System.out.println(deque); // [a1, b1, b2, c1, c2, c3]

void addFirst (E e)

容量制限に違反することなく指定された要素をこの両端キューの先頭にすぐに挿入できる場合には、そうします。使用可能な空き領域がその時点で存在しない場合はIllegalStateExceptionをスローします。

// capacity = 3
final Deque<String> deque = new LinkedBlockingDeque<>(3);
System.out.println(deque); // []

deque.addFirst("aaa");
System.out.println(deque); // [aaa]

deque.addFirst("bbb");
System.out.println(deque); // [bbb, aaa]

deque.addFirst("ccc");
System.out.println(deque); // [ccc, bbb, aaa]

try {
    deque.addFirst("ddd");
} catch (IllegalStateException e) {
    System.out.println("IllegalStateException! : " + e.getMessage());
}

// 結果
// ↓
//IllegalStateException! : Deque full

void addLast (E e)

容量制限に違反することなく指定された要素をこの両端キューの末尾にすぐに挿入できる場合には、そうします。使用可能な空き領域がその時点で存在しない場合はIllegalStateExceptionをスローします。

// capacity = 3
final Deque<String> deque = new LinkedBlockingDeque<>(3);
System.out.println(deque); // []

deque.addLast("aaa");
System.out.println(deque); // [aaa]

deque.addLast("bbb");
System.out.println(deque); // [aaa, bbb]

deque.addLast("ccc");
System.out.println(deque); // [aaa, bbb, ccc]

try {
    deque.addLast("ddd");
} catch (IllegalStateException e) {
    System.out.println("IllegalStateException! : " + e.getMessage());
}

// 結果
// ↓
//IllegalStateException! : Deque full

boolean contains (Object o)

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

final Deque<String> deque = new ArrayDeque<>(List.of("aaa", "bbb", "ccc"));
System.out.println(deque); // [aaa, bbb, ccc]

System.out.println(deque.contains("aaa")); // true
System.out.println(deque.contains("bbb")); // true
System.out.println(deque.contains("XXX")); // false

Iterator<E> descendingIterator ()

この両端キュー内の要素を逆順で反復処理するイテレータを返します。

final Deque<String> deque = new ArrayDeque<>(List.of("aaa", "bbb", "ccc"));
System.out.println(deque); // [aaa, bbb, ccc]

final var iterator = deque.descendingIterator();

System.out.println("-- forEachRemaining --");
iterator.forEachRemaining(System.out::println);

// 結果
// ↓
//-- forEachRemaining --
//ccc
//bbb
//aaa

E element ()

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

このメソッドは getFirst() と同等です。
そちらのAPI使用例をご参照ください。

E getFirst ()

この両端キューの最初の要素を取得しますが、削除はしません。

final Deque<String> deque = new ArrayDeque<>();
System.out.println(deque); // []

deque.addLast("aaa");
deque.addLast("bbb");
deque.addLast("ccc");

System.out.println(deque.getFirst()); // aaa
System.out.println(deque); // [aaa, bbb, ccc]

System.out.println(deque.removeFirst()); // aaa
System.out.println(deque); // [bbb, ccc]

System.out.println(deque.getFirst()); // bbb
System.out.println(deque); // [bbb, ccc]

System.out.println(deque.removeFirst()); // bbb
System.out.println(deque); // [ccc]

System.out.println(deque.getFirst()); // ccc
System.out.println(deque); // [ccc]

System.out.println(deque.removeFirst()); // ccc
System.out.println(deque); // []

try {
    deque.getFirst();
} catch (NoSuchElementException e) {
    System.out.println("NoSuchElementException!");
}

// 結果
// ↓
//NoSuchElementException!

E getLast ()

この両端キューの最後の要素を取得しますが、削除はしません。

final Deque<String> deque = new ArrayDeque<>();
System.out.println(deque); // []

deque.addLast("aaa");
deque.addLast("bbb");
deque.addLast("ccc");

System.out.println(deque.getLast()); // ccc
System.out.println(deque); // [aaa, bbb, ccc]

System.out.println(deque.removeLast()); // ccc
System.out.println(deque); // [aaa, bbb]

System.out.println(deque.getLast()); // bbb
System.out.println(deque); // [aaa, bbb]

System.out.println(deque.removeLast()); // bbb
System.out.println(deque); // [aaa]

System.out.println(deque.getLast()); // aaa
System.out.println(deque); // [aaa]

System.out.println(deque.removeLast()); // aaa
System.out.println(deque); // []

try {
    deque.getLast();
} catch (NoSuchElementException e) {
    System.out.println("NoSuchElementException!");
}

// 結果
// ↓
//NoSuchElementException!

Iterator<E> iterator ()

この両端キュー内の要素を適切な順序で反復処理するイテレータを返します。

final Deque<String> deque = new ArrayDeque<>(List.of("aaa", "bbb", "ccc"));
System.out.println(deque); // [aaa, bbb, ccc]

final var iterator = deque.iterator();

System.out.println("-- forEachRemaining --");
iterator.forEachRemaining(System.out::println);

// 結果
// ↓
//-- forEachRemaining --
//aaa
//bbb
//ccc

boolean offer (E e)

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

このメソッドは offerLast(E e) と同等です。
そちらのAPI使用例をご参照ください。

boolean offerFirst (E e)

容量制限に違反しないかぎり、指定された要素をこの両端キューの先頭に挿入します。

// capacity = 3
final Deque<String> deque = new LinkedBlockingDeque<>(3);
System.out.println(deque); // []

System.out.println(deque.offerFirst("aaa")); // true
System.out.println(deque); // [aaa]

System.out.println(deque.offerFirst("bbb")); // true
System.out.println(deque); // [bbb, aaa]

System.out.println(deque.offerFirst("ccc")); // true
System.out.println(deque); // [ccc, bbb, aaa]

System.out.println(deque.offerFirst("ddd")); // false
System.out.println(deque); // [ccc, bbb, aaa]

boolean offerLast (E e)

容量制限に違反しないかぎり、指定された要素をこの両端キューの末尾に挿入します。

// capacity = 3
final Deque<String> deque = new LinkedBlockingDeque<>(3);
System.out.println(deque); // []

System.out.println(deque.offerLast("aaa")); // true
System.out.println(deque); // [aaa]

System.out.println(deque.offerLast("bbb")); // true
System.out.println(deque); // [aaa, bbb]

System.out.println(deque.offerLast("ccc")); // true
System.out.println(deque); // [aaa, bbb, ccc]

System.out.println(deque.offerLast("ddd")); // false
System.out.println(deque); // [aaa, bbb, ccc]

E peek ()

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

このメソッドは peekFirst() と同等です。
そちらのAPI使用例をご参照ください。

E peekFirst ()

この両端キューの最初の要素を取得しますが、削除しません。両端キューが空の場合はnullを返します。

final Deque<String> deque = new ArrayDeque<>();
System.out.println(deque); // []

deque.addLast("aaa");
deque.addLast("bbb");
deque.addLast("ccc");

System.out.println(deque.peekFirst()); // aaa
System.out.println(deque); // [aaa, bbb, ccc]

System.out.println(deque.pollFirst()); // aaa
System.out.println(deque); // [bbb, ccc]

System.out.println(deque.peekFirst()); // bbb
System.out.println(deque); // [bbb, ccc]

System.out.println(deque.pollFirst()); // bbb
System.out.println(deque); // [ccc]

System.out.println(deque.peekFirst()); // ccc
System.out.println(deque); // [ccc]

System.out.println(deque.pollFirst()); // ccc
System.out.println(deque); // []

System.out.println(deque.peekFirst()); // null
System.out.println(deque); // []

E peekLast ()

この両端キューの最後の要素を取得しますが、削除しません。両端キューが空の場合はnullを返します。

final Deque<String> deque = new ArrayDeque<>();
System.out.println(deque); // []

deque.addLast("aaa");
deque.addLast("bbb");
deque.addLast("ccc");

System.out.println(deque.peekLast()); // ccc
System.out.println(deque); // [aaa, bbb, ccc]

System.out.println(deque.pollLast()); // ccc
System.out.println(deque); // [aaa, bbb]

System.out.println(deque.peekLast()); // bbb
System.out.println(deque); // [aaa, bbb]

System.out.println(deque.pollLast()); // bbb
System.out.println(deque); // [aaa]

System.out.println(deque.peekLast()); // aaa
System.out.println(deque); // [aaa]

System.out.println(deque.pollLast()); // aaa
System.out.println(deque); // []

System.out.println(deque.peekLast()); // null
System.out.println(deque); // []

E poll ()

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

このメソッドは pollFirst() と同等です。
そちらのAPI使用例をご参照ください。

E pollFirst ()

この両端キューの最初の要素を取得および削除します。両端キューが空の場合はnullを返します。

final Deque<String> deque = new ArrayDeque<>();
System.out.println(deque); // []

deque.add("aaa");
deque.add("bbb");
deque.add("ccc");

System.out.println(deque); // [aaa, bbb, ccc]

System.out.println(deque.pollFirst()); // aaa
System.out.println(deque); // [bbb, ccc]

System.out.println(deque.pollFirst()); // bbb
System.out.println(deque); // [ccc]

System.out.println(deque.pollFirst()); // ccc
System.out.println(deque); // []

System.out.println(deque.pollFirst()); // null
System.out.println(deque); // []

E pollLast ()

この両端キューの最後の要素を取得および削除します。両端キューが空の場合はnullを返します。

final Deque<String> deque = new ArrayDeque<>();
System.out.println(deque); // []

deque.add("aaa");
deque.add("bbb");
deque.add("ccc");

System.out.println(deque); // [aaa, bbb, ccc]

System.out.println(deque.pollLast()); // ccc
System.out.println(deque); // [aaa, bbb]

System.out.println(deque.pollLast()); // bbb
System.out.println(deque); // [aaa]

System.out.println(deque.pollLast()); // aaa
System.out.println(deque); // []

System.out.println(deque.pollLast()); // null
System.out.println(deque); // []

E pop ()

この両端キューで表されるスタックに要素をポップします。

このメソッドは removeFirst() と同等です。
そちらのAPI使用例をご参照ください。

void push (E e)

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

このメソッドは addFirst(E e) と同等です。
そちらのAPI使用例をご参照ください。

E remove ()

この両端キューによって表されるキューの先頭(つまり、この両端キューの最初の要素)を取得して削除します。

このメソッドは removeFirst() と同等です。
そちらのAPI使用例をご参照ください。

boolean remove (Object o)

指定された要素のうち最初に出現したものを、この両端キューから削除します。

このメソッドは removeFirstOccurrence(Object o) と同等です。
そちらのAPI使用例をご参照ください。

E removeFirst ()

この両端キューの最初の要素を取得して削除します。

final Deque<String> deque = new ArrayDeque<>();
System.out.println(deque); // []

deque.add("aaa");
deque.add("bbb");
deque.add("ccc");

System.out.println(deque); // [aaa, bbb, ccc]

System.out.println(deque.removeFirst()); // aaa
System.out.println(deque); // [bbb, ccc]

System.out.println(deque.removeFirst()); // bbb
System.out.println(deque); // [ccc]

System.out.println(deque.removeFirst()); // ccc
System.out.println(deque); // []

try {
    deque.removeFirst();
} catch (NoSuchElementException e) {
    System.out.println("NoSuchElementException!");
}

// 結果
// ↓
//NoSuchElementException!

boolean removeFirstOccurrence (Object o)