Programming TIPS!

A site on Java API Examples and TIPS.
All Posts
Japanese Site

Java : Deque with Examples

Last Modified : February 10, 2024 Published : June 11, 2022

Deque (Java SE 20 & JDK 20) API Examples.
You will find code examples on most Deque methods.


Summary

A linear collection that supports element insertion and removal at both ends. The name deque is short for "double ended queue" and is usually pronounced "deck".

Deque (Java SE 20 & JDK 20)

Class diagram

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); // []

Methods

boolean add (E e)

Inserts the specified element into the queue represented by this deque (in other words, at the tail of this deque) if it is possible to do so immediately without violating capacity restrictions, returning true upon success and throwing an IllegalStateException if no space is currently available.

Deque (Java SE 20 & JDK 20)

This method is equivalent to addLast(E e).

boolean addAll (Collection<? extends E> c)

Adds all of the elements in the specified collection at the end of this deque, as if by calling addLast(E) on each one, in the order that they are returned by the collection's iterator.

Deque (Java SE 20 & JDK 20) 
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)

Inserts the specified element at the front of this deque if it is possible to do so immediately without violating capacity restrictions, throwing an IllegalStateException if no space is currently available.

Deque (Java SE 20 & JDK 20) 
// 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());
}

// Result
// ↓
//IllegalStateException! : Deque full

void addLast (E e)

Inserts the specified element at the end of this deque if it is possible to do so immediately without violating capacity restrictions, throwing an IllegalStateException if no space is currently available.

Deque (Java SE 20 & JDK 20) 
// 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());
}

// Result
// ↓
//IllegalStateException! : Deque full

boolean contains (Object o)

Returns true if this deque contains the specified element.

Deque (Java SE 20 & JDK 20) 
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 ()

Returns an iterator over the elements in this deque in reverse sequential order.

Deque (Java SE 20 & JDK 20) 
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);

// Result
// ↓
//-- forEachRemaining --
//ccc
//bbb
//aaa

E element ()

Retrieves, but does not remove, the head of the queue represented by this deque (in other words, the first element of this deque).

Deque (Java SE 20 & JDK 20)

This method is equivalent to getFirst().

E getFirst ()

Retrieves, but does not remove, the first element of this deque.

Deque (Java SE 20 & JDK 20) 
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!");
}

// Result
// ↓
//NoSuchElementException!

E getLast ()

Retrieves, but does not remove, the last element of this deque.

Deque (Java SE 20 & JDK 20) 
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!");
}

// Result
// ↓
//NoSuchElementException!

Iterator<E> iterator ()

Returns an iterator over the elements in this deque in proper sequence.

Deque (Java SE 20 & JDK 20) 
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);

// Result
// ↓
//-- forEachRemaining --
//aaa
//bbb
//ccc

boolean offer (E e)

Inserts the specified element into the queue represented by this deque (in other words, at the tail of this deque) if it is possible to do so immediately without violating capacity restrictions, returning true upon success and false if no space is currently available.

Deque (Java SE 20 & JDK 20)

This method is equivalent to offerLast(E e).

boolean offerFirst (E e)

Inserts the specified element at the front of this deque unless it would violate capacity restrictions.

Deque (Java SE 20 & JDK 20) 
// 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)

Inserts the specified element at the end of this deque unless it would violate capacity restrictions.

Deque (Java SE 20 & JDK 20) 
// 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 ()

Retrieves, but does not remove, the head of the queue represented by this deque (in other words, the first element of this deque), or returns null if this deque is empty.

Deque (Java SE 20 & JDK 20)

This method is equivalent to peekFirst().

E peekFirst ()

Retrieves, but does not remove, the first element of this deque, or returns null if this deque is empty.

Deque (Java SE 20 & JDK 20) 
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 ()

Retrieves, but does not remove, the last element of this deque, or returns null if this deque is empty.

Deque (Java SE 20 & JDK 20) 
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 ()

Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque), or returns null if this deque is empty.

Deque (Java SE 20 & JDK 20)

This method is equivalent to pollFirst().

E pollFirst ()

Retrieves and removes the first element of this deque, or returns null if this deque is empty.

Deque (Java SE 20 & JDK 20) 
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 ()

Retrieves and removes the last element of this deque, or returns null if this deque is empty.

Deque (Java SE 20 & JDK 20) 
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 ()

Pops an element from the stack represented by this deque.

Deque (Java SE 20 & JDK 20)

This method is equivalent to removeFirst().

void push (E e)

Pushes an element onto the stack represented by this deque (in other words, at the head of this deque) if it is possible to do so immediately without violating capacity restrictions, throwing an IllegalStateException if no space is currently available.

Deque (Java SE 20 & JDK 20)

This method is equivalent to addFirst(E e).

E remove ()

Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque).

Deque (Java SE 20 & JDK 20)

This method is equivalent to removeFirst().

boolean remove (Object o)

Removes the first occurrence of the specified element from this deque.

Deque (Java SE 20 & JDK 20)

This method is equivalent to removeFirstOccurrence(Object o).

E removeFirst ()

Retrieves and removes the first element of this deque.

Deque (Java SE 20 & JDK 20) 
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!");
}

// Result
// ↓
//NoSuchElementException!

boolean removeFirstOccurrence (Object o)

Removes the first occurrence of the specified element from this deque.

Deque (Java SE 20 & JDK 20) 
final Deque<String> deque = new ArrayDeque<>(List.of("aaa", "BBB", "aaa", "BBB", "ccc"));
System.out.println(deque); // [aaa, BBB, aaa, BBB, ccc]

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

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

System.out.println(deque.removeFirstOccurrence("XXX")); // false
System.out.println(deque); // [aaa, BBB, ccc]

E removeLast ()

Retrieves and removes the last element of this deque.

Deque (Java SE 20 & JDK 20) 
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.removeLast()); // ccc
System.out.println(deque); // [aaa, bbb]

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

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

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

// Result
// ↓
//NoSuchElementException!

boolean removeLastOccurrence (Object o)

Removes the last occurrence of the specified element from this deque.

Deque (Java SE 20 & JDK 20) 
final Deque<String> deque = new ArrayDeque<>(List.of("aaa", "BBB", "aaa", "BBB", "ccc"));
System.out.println(deque); // [aaa, BBB, aaa, BBB, ccc]

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

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

System.out.println(deque.removeLastOccurrence("XXX")); // false
System.out.println(deque); // [aaa, BBB, ccc]

int size ()

Returns the number of elements in this deque.

Deque (Java SE 20 & JDK 20) 
final Deque<String> deque = new ArrayDeque<>();
System.out.println(deque); // []
System.out.println(deque.size()); // 0

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

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

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

Methods declared in Collection

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

Please see the link below.

Methods declared in Iterable

forEach

Please see the link below.


Related posts

To top of page