Java : ArrayDeque with Examples

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


Summary

Resizable-array implementation of the Deque interface. Array deques have no capacity restrictions; they grow as necessary to support usage.

Class diagram

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

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 var deque = new ArrayDeque<String>();

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

Constructors

ArrayDeque ()

Constructs an empty array deque with an initial capacity sufficient to hold 16 elements.

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

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

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

ArrayDeque (int numElements)

Constructs an empty array deque with an initial capacity sufficient to hold the specified number of elements.

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

final var startTime = System.nanoTime();

for (int i = 0; i < 1000000; i++) {
    deque.addLast(String.valueOf(i));
}

final var endTime = System.nanoTime();

// 0.053015 sec.
System.out.printf("%f sec.%n", (endTime - startTime) / 1000000000.0);
final var deque = new ArrayDeque<String>(1);
System.out.println(deque); // []

final var startTime = System.nanoTime();

for (int i = 0; i < 1000000; i++) {
    deque.addLast(String.valueOf(i));
}

final var endTime = System.nanoTime();

// 0.066947 sec.
System.out.printf("%f sec.%n", (endTime - startTime) / 1000000000.0);

ArrayDeque (Collection<? extends E> c)

Constructs a deque containing the elements of the specified collection, in the order they are returned by the collection's iterator.

final var c = List.of("a", "b", "c");

final var deque = new ArrayDeque<>(c);
System.out.println(deque); // [a, b, c]
System.out.println(deque.size()); // 3

Methods

boolean add (E e)

Inserts the specified element at the end of this deque.

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.

final var deque = new ArrayDeque<String>();
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.

final var deque = new ArrayDeque<String>();
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]

void addLast (E e)

Inserts the specified element at the end of this deque.

final var deque = new ArrayDeque<String>();
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]

void clear ()

Removes all of the elements from this deque.

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

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

deque.addLast("b");
System.out.println(deque); // [a, b]

deque.clear();
System.out.println(deque); // []

ArrayDeque<E> clone ()

Returns a copy of this deque.

final var deque = new ArrayDeque<String>();
deque.addLast("a");
deque.addLast("b");
deque.addLast("c");

System.out.println(deque); // [a, b, c]

final var cloned = deque.clone();
System.out.println(cloned); // [a, b, c]
System.out.println(cloned.getClass()); // class java.util.ArrayDeque

boolean contains (Object o)

Returns true if this deque contains the specified element.

final var 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.

final var 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.

This method is equivalent to getFirst().

void forEach (Consumer<? super E> action)

Performs the given action for each element of the Iterable until all elements have been processed or the action throws an exception.

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

System.out.println("-- forEach --");
deque.forEach(value -> {
    System.out.println("value = " + value);
});

// Result
// ↓
//-- forEach --
//value = aaa
//value = bbb
//value = ccc

E getFirst ()

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

final var deque = new ArrayDeque<String>();
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(e);
}

// Result
// ↓
//java.util.NoSuchElementException

E getLast ()

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

final var deque = new ArrayDeque<String>();
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(e);
}

// Result
// ↓
//java.util.NoSuchElementException

boolean isEmpty ()

Returns true if this deque contains no elements.

final var deque = new ArrayDeque<String>();
deque.addLast("a");
deque.addLast("b");
deque.addLast("c");

System.out.println(deque); // [a, b, c]
System.out.println(deque.isEmpty()); // false

deque.clear();
System.out.println(deque); // []
System.out.println(deque.isEmpty()); // true

Iterator<E> iterator ()

Returns an iterator over the elements in this deque.

final var 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(value -> {
    System.out.println("value = " + value);
});

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

boolean offer (E e)

Inserts the specified element at the end of this deque.

This method is equivalent to offerLast(E e).

boolean offerFirst (E e)

Inserts the specified element at the front of this deque.

final var deque = new ArrayDeque<String>();
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]

boolean offerLast (E e)

Inserts the specified element at the end of this deque.

final var deque = new ArrayDeque<String>();
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]

E peek ()

Retrieves, but does not remove, the head of the queue represented by this deque, or returns null if this deque is empty.

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.

final var deque = new ArrayDeque<String>();
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.

final var deque = new ArrayDeque<String>();
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.

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.

final var deque = new ArrayDeque<String>();
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.

final var deque = new ArrayDeque<String>();
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.

This method is equivalent to removeFirst().

void push (E e)

Pushes an element onto the stack represented by this deque.

This method is equivalent to addFirst(E e).

E remove ()

Retrieves and removes the head of the queue represented by this deque.

This method is equivalent to removeFirst().

boolean remove (Object o)

Removes a single instance of the specified element from this deque.

This method is equivalent to removeFirstOccurrence(Object o).

boolean removeAll (Collection<?> c)

Removes all of this collection's elements that are also contained in the specified collection (optional operation).

final var src = List.of("a", "b", "a", "b", "A", "B");
System.out.println(src); // [a, b, a, b, A, B]

{
    final var deque = new ArrayDeque<>(src);
    System.out.println(deque); // [a, b, a, b, A, B]

    System.out.println(deque.removeAll(List.of())); // false
    System.out.println(deque); // [a, b, a, b, A, B]
}
{
    final var deque = new ArrayDeque<>(src);
    System.out.println(deque); // [a, b, a, b, A, B]

    System.out.println(deque.removeAll(List.of("a"))); // true
    System.out.println(deque); // [b, b, A, B]
}
{
    final var deque = new ArrayDeque<>(src);
    System.out.println(deque); // [a, b, a, b, A, B]

    System.out.println(deque.removeAll(List.of("a", "b"))); // true
    System.out.println(deque); // [A, B]
}
{
    final var deque = new ArrayDeque<>(src);
    System.out.println(deque); // [a, b, a, b, A, B]

    System.out.println(deque.removeAll(List.of("b", "a"))); // true
    System.out.println(deque); // [A, B]
}
{
    final var deque = new ArrayDeque<>(src);
    System.out.println(deque); // [a, b, a, b, A, B]

    System.out.println(deque.removeAll(List.of("A"))); // true
    System.out.println(deque); // [a, b, a, b, B]
}
{
    final var deque = new ArrayDeque<>(src);
    System.out.println(deque); // [a, b, a, b, A, B]

    System.out.println(deque.removeAll(List.of("X", "Y", "Z"))); // false
    System.out.println(deque); // [a, b, a, b, A, B]
}
{
    final var deque = new ArrayDeque<>(src);
    System.out.println(deque); // [a, b, a, b, A, B]

    System.out.println(deque.removeAll(List.of("A", "X", "Y", "Z"))); // true
    System.out.println(deque); // [a, b, a, b, B]
}

E removeFirst ()

Retrieves and removes the first element of this deque.

final var deque = new ArrayDeque<String>();
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(e);
}

// Result
// ↓
//java.util.NoSuchElementException

boolean removeFirstOccurrence (Object o)

Removes the first occurrence of the specified element in this deque (when traversing the deque from head to tail).

final var 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("BBB")); // true
System.out.println(deque); // [aaa, ccc]

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

boolean removeIf (Predicate<? super E> filter)

Removes all of the elements of this collection that satisfy the given predicate.

final var deque = new ArrayDeque<String>();
deque.addLast("aaa");
deque.addLast("BBB");
deque.addLast("ccc");
deque.addLast("DDD");

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

final var ret = deque.removeIf(s -> {
    return s.equals(s.toUpperCase());
});

System.out.println(ret); // true
System.out.println(deque); // [aaa, ccc]
final var deque = new ArrayDeque<String>();
deque.addLast("aaa");
deque.addLast("bbb");

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

final var ret = deque.removeIf(s -> s.equals(s.toUpperCase()));

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

E removeLast ()

Retrieves and removes the last element of this deque.

final var deque = new ArrayDeque<String>();
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(e);
}

// Result
// ↓
//java.util.NoSuchElementException

boolean removeLastOccurrence (Object o)

Removes the last occurrence of the specified element in this deque (when traversing the deque from head to tail).

final var 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]

boolean retainAll (Collection<?> c)

Retains only the elements in this collection that are contained in the specified collection (optional operation).

final var src = List.of("a", "b", "a", "b", "A", "B");
System.out.println(src); // [a, b, a, b, A, B]

{
    final var deque = new ArrayDeque<>(src);
    System.out.println(deque); // [a, b, a, b, A, B]

    System.out.println(deque.retainAll(List.of())); // true
    System.out.println(deque); // []
}
{
    final var deque = new ArrayDeque<>(src);
    System.out.println(deque); // [a, b, a, b, A, B]

    System.out.println(deque.retainAll(List.of("a", "b"))); // true
    System.out.println(deque); // [a, b, a, b]
}
{
    final var deque = new ArrayDeque<>(src);
    System.out.println(deque); // [a, b, a, b, A, B]

    System.out.println(deque.retainAll(List.of("b", "a"))); // true
    System.out.println(deque); // [a, b, a, b]
}
{
    final var deque = new ArrayDeque<>(src);
    System.out.println(deque); // [a, b, a, b, A, B]

    System.out.println(deque.retainAll(List.of("A"))); // true
    System.out.println(deque); // [A]
}
{
    final var deque = new ArrayDeque<>(src);
    System.out.println(deque); // [a, b, a, b, A, B]

    System.out.println(deque.retainAll(List.of("X", "Y", "Z"))); // true
    System.out.println(deque); // []
}
{
    final var deque = new ArrayDeque<>(src);
    System.out.println(deque); // [a, b, a, b, A, B]

    System.out.println(deque.retainAll(List.of("A", "X", "Y", "Z"))); // true
    System.out.println(deque); // [A]
}
{
    final var deque = new ArrayDeque<>(src);
    System.out.println(deque); // [a, b, a, b, A, B]

    System.out.println(deque.retainAll(List.of("a", "b", "A", "B"))); // false
    System.out.println(deque); // [a, b, a, b, A, B]
}

int size ()

Returns the number of elements in this deque.

final var deque = new ArrayDeque<String>();
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

Spliterator<E> spliterator ()

Creates a late-binding and fail-fast Spliterator over the elements in this deque.

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

final var spliterator = deque.spliterator();

System.out.println("-- forEachRemaining --");
spliterator.forEachRemaining(value -> {
    System.out.println("value = " + value);
});

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

Object[] toArray ()

Returns an array containing all of the elements in this deque in proper sequence (from first to last element).

final var deque = new ArrayDeque<>(List.of("a", "b", "c"));
System.out.println(deque); // [a, b, c]

final Object[] array = deque.toArray();
System.out.println(Arrays.toString(array)); // [a, b, c]

<T> T[] toArray (T[] a)

Returns an array containing all of the elements in this deque in proper sequence (from first to last element); the runtime type of the returned array is that of the specified array.

final var deque = new ArrayDeque<>(List.of("a", "b", "c"));
System.out.println(deque); // [a, b, c]

final String[] array = deque.toArray(new String[0]);
System.out.println(Arrays.toString(array)); // [a, b, c]
final var deque = new ArrayDeque<>(List.of("a", "b", "c"));
System.out.println(deque); // [a, b, c]

{
    final String[] array = new String[3];
    System.out.println(Arrays.toString(array)); // [null, null, null]

    final var ret = deque.toArray(array);
    System.out.println(Arrays.toString(array)); // [a, b, c]
    System.out.println(Arrays.toString(ret)); // [a, b, c]
}
{
    final String[] array = new String[5];
    System.out.println(Arrays.toString(array)); // [null, null, null, null, null]

    final var ret = deque.toArray(array);
    System.out.println(Arrays.toString(array)); // [a, b, c, null, null]
    System.out.println(Arrays.toString(ret)); // [a, b, c, null, null]
}
{
    final String[] array = new String[1];
    System.out.println(Arrays.toString(array)); // [null]

    final var ret = deque.toArray(array);
    System.out.println(Arrays.toString(array)); // [null]
    System.out.println(Arrays.toString(ret)); // [a, b, c]
}

Methods declared in AbstractCollection

containsAll, toString

Please see the link below.

Methods declared in Collection

containsAll, equals, hashCode, parallelStream, stream, toArray

Please see the link below.


Related posts

To top of page