Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / Java

Working with both ends of a Deque

Learn to insert, inspect, and remove elements at either end of a `Deque`, and know when to expect `false`, `null`, or an exception.

Version: Java SE 21

Syntax

java.util.Deque<E> — instance method signatures:
boolean offerLast(E e)
boolean offerFirst(E e)
E peekFirst()
E peekLast()
E pollFirst()
E pollLast()
E pop()
void push(E e)
E removeFirst()

java.util.Deque<E> is the double-ended queue interface. First means the front, Last means the back, and E is the element type.

Deque.offerLast, called as deque.offerLast(e), inserts at the back; offerFirst(e) inserts at the front. Both return true on insertion or false if a capacity limit prevents immediate insertion. An invalid element can still cause an exception, such as NullPointerException if the implementation disallows null.

peekFirst() and peekLast() read the front and back elements respectively without removing them. pollFirst() and pollLast() return and remove the element at the corresponding end. All four return null when the deque is empty. For a FIFO queue, pair offerLast(e) with pollFirst() so the earliest insertion is removed first.

push(e) is equivalent to addFirst(e): it adds at the front, returns no value, and throws IllegalStateException if a capacity limit prevents insertion. pop() is equivalent to removeFirst(): both return and remove the front element, but on an empty deque both throw NoSuchElementException rather than returning null like pollFirst(). Pair push(e) with pop() for a LIFO stack: the most recently pushed element comes out first.

The example uses ArrayDeque, which grows as needed, has no fixed capacity limit, and rejects null. Avoid inserting null even in implementations that allow it: a null result from a peek… or poll… method would no longer distinguish an empty deque from a null element.

Examples

import java.util.ArrayDeque;
import java.util.Deque;
import java.util.NoSuchElementException;

public class DequeEndsDemo {
    public static void main(String[] args) {
        Deque<String> deque = new ArrayDeque<>();

        System.out.println("offerLast: " + deque.offerLast("B"));
        System.out.println("offerFirst: " + deque.offerFirst("A"));
        System.out.println("peekFirst: " + deque.peekFirst());
        System.out.println("peekLast: " + deque.peekLast());
        System.out.println("pollLast: " + deque.pollLast());
        System.out.println("pollFirst: " + deque.pollFirst());
        System.out.println("empty pollFirst: " + deque.pollFirst());

        deque.push("X");
        deque.push("Y");
        System.out.println("pop: " + deque.pop());
        System.out.println("removeFirst: " + deque.removeFirst());
        try {
            deque.pop();
        } catch (NoSuchElementException e) {
            System.out.println("empty pop: NoSuchElementException");
        }
    }
}

Result

offerLast: true
offerFirst: true
peekFirst: A
peekLast: B
pollLast: B
pollFirst: A
empty pollFirst: null
pop: Y
removeFirst: X
empty pop: NoSuchElementException

The peek calls leave `A` and `B` in the deque, and the poll calls remove them. After pushing `X` and `Y`, `Y` comes off first. The example also contrasts the `null` result from `pollFirst()` with the caught exception from `pop()` on an empty deque.

Related lessons

  • Java · Lesson 60 · Basic · Version: 2

Sources