Java : PriorityQueue with Examples

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

Summary

An unbounded priority queue based on a priority heap. The elements of the priority queue are ordered according to their natural ordering, or by a Comparator provided at queue construction time, depending on which constructor is used.

Class diagram

record Item(String value, int priority) {
    @Override
    public String toString() {
        return "%s(%d)".formatted(value, priority);
    }
}

final var comparator = Comparator.comparingInt(Item::priority);

final var queue = new PriorityQueue<Item>(comparator);
System.out.println(queue); // []

System.out.println(queue.offer(new Item("aaa", 1))); // true
System.out.println(queue.offer(new Item("bbb", 2))); // true
System.out.println(queue.offer(new Item("ccc", 3))); // true
System.out.println(queue.offer(new Item("XXX", 100))); // true
System.out.println(queue.offer(new Item("YYY", 99))); // true
System.out.println(queue.offer(new Item("ZZZ", 98))); // true

System.out.println(queue); // [aaa(1), bbb(2), ccc(3), XXX(100), YYY(99), ZZZ(98)]

System.out.println(queue.poll()); // aaa(1)
System.out.println(queue.poll()); // bbb(2)
System.out.println(queue.poll()); // ccc(3)
System.out.println(queue.poll()); // ZZZ(98)
System.out.println(queue.poll()); // YYY(99)
System.out.println(queue.poll()); // XXX(100)

Constructors

PriorityQueue ()

Creates a PriorityQueue with the default initial capacity (11) that orders its elements according to their natural ordering.

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

System.out.println(queue.offer("aaa")); // true
System.out.println(queue.offer("bbb")); // true
System.out.println(queue.offer("ccc")); // true

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

PriorityQueue (int initialCapacity)

Creates a PriorityQueue with the specified initial capacity that orders its elements according to their natural ordering.

final var queue = new PriorityQueue<Integer>(10000000);
System.out.println(queue); // []

final var startTime = System.nanoTime();

for (int i = 0; i < 4000000; i++) {
    queue.add(i);
}

final var endTime = System.nanoTime();

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

final var queue = new PriorityQueue<Integer>(1);
System.out.println(queue); // []

final var startTime = System.nanoTime();

for (int i = 0; i < 4000000; i++) {
    queue.add(i);
}

final var endTime = System.nanoTime();

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

PriorityQueue (int initialCapacity, Comparator<? super E> comparator)

Creates a PriorityQueue with the specified initial capacity that orders its elements according to the specified comparator.

Please see :

PriorityQueue(int initialCapacity) for initialCapacity parameter.
PriorityQueue(Comparator<? super E> comparator) for comparator parameter.

PriorityQueue (Collection<? extends E> c)

Creates a PriorityQueue containing the elements in the specified collection.

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

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

PriorityQueue (Comparator<? super E> comparator)

Creates a PriorityQueue with the default initial capacity and whose elements are ordered according to the specified comparator.

record Item(String value, int priority) {
    @Override
    public String toString() {
        return "%s(%d)".formatted(value, priority);
    }
}

final var comparator = Comparator.comparingInt(Item::priority);

final var queue = new PriorityQueue<Item>(comparator);
System.out.println(queue); // []

System.out.println(queue.offer(new Item("aaa", 1))); // true
System.out.println(queue.offer(new Item("bbb", 2))); // true
System.out.println(queue.offer(new Item("ccc", 3))); // true
System.out.println(queue.offer(new Item("XXX", 100))); // true
System.out.println(queue.offer(new Item("YYY", 99))); // true
System.out.println(queue.offer(new Item("ZZZ", 98))); // true

System.out.println(queue); // [aaa(1), bbb(2), ccc(3), XXX(100), YYY(99), ZZZ(98)]

System.out.println(queue.poll()); // aaa(1)
System.out.println(queue.poll()); // bbb(2)
System.out.println(queue.poll()); // ccc(3)
System.out.println(queue.poll()); // ZZZ(98)
System.out.println(queue.poll()); // YYY(99)
System.out.println(queue.poll()); // XXX(100)

PriorityQueue (PriorityQueue<? extends E> c)

Creates a PriorityQueue containing the elements in the specified priority queue.

final var c = new PriorityQueue<String>(Comparator.reverseOrder());
System.out.println(c.offer("aaa")); // true
System.out.println(c.offer("bbb")); // true
System.out.println(c.offer("ccc")); // true

final var queue = new PriorityQueue<>(c);

System.out.println(queue.poll()); // ccc
System.out.println(queue.poll()); // bbb
System.out.println(queue.poll()); // aaa

PriorityQueue (SortedSet<? extends E> c)

Creates a PriorityQueue containing the elements in the specified sorted set.

final var c = new TreeSet<String>(Comparator.reverseOrder());
System.out.println(c.add("aaa")); // true
System.out.println(c.add("bbb")); // true
System.out.println(c.add("ccc")); // true

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

final var queue = new PriorityQueue<>(c);

System.out.println(queue.poll()); // ccc
System.out.println(queue.poll()); // bbb
System.out.println(queue.poll()); // aaa

Methods

boolean add (E e)

Inserts the specified element into this priority queue.

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

System.out.println(queue.add("aaa")); // true
System.out.println(queue); // [aaa]

System.out.println(queue.add("bbb")); // true
System.out.println(queue); // [aaa, bbb]

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

void clear ()

Removes all of the elements from this priority queue.

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

System.out.println(queue.offer("a")); // true
System.out.println(queue); // [a]

System.out.println(queue.offer("b")); // true
System.out.println(queue); // [a, b]

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

Comparator<? super E> comparator ()

Returns the comparator used to order the elements in this queue, or null if this queue is sorted according to the natural ordering of its elements.

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

final var comparator = queue.comparator();
System.out.println(comparator); // null

final var queue = new PriorityQueue<String>(Comparator.reverseOrder());
System.out.println(queue); // []

final var comparator = queue.comparator();
System.out.println(Objects.equals(comparator, Comparator.reverseOrder())); // true

final var queue = new PriorityQueue<>(String.CASE_INSENSITIVE_ORDER);
System.out.println(queue); // []

final var comparator = queue.comparator();
System.out.println(Objects.equals(comparator, String.CASE_INSENSITIVE_ORDER)); // true

boolean contains (Object o)

Returns true if this queue contains the specified element.

final var queue = new PriorityQueue<String>();

System.out.println(queue.offer("aaa")); // true
System.out.println(queue.offer("bbb")); // true
System.out.println(queue.offer("ccc")); // true

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

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

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 queue = new PriorityQueue<String>();

System.out.println(queue.offer("aaa")); // true
System.out.println(queue.offer("bbb")); // true
System.out.println(queue.offer("ccc")); // true

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

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

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

Iterator<E> iterator ()

Returns an iterator over the elements in this queue.

final var queue = new PriorityQueue<String>();

System.out.println(queue.offer("aaa")); // true
System.out.println(queue.offer("bbb")); // true
System.out.println(queue.offer("ccc")); // true

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

final var iterator = queue.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 into this priority queue.

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

System.out.println(queue.offer("aaa")); // true
System.out.println(queue); // [aaa]

System.out.println(queue.offer("bbb")); // true
System.out.println(queue); // [aaa, bbb]

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

E peek ()

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

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

System.out.println(queue.offer("aaa")); // true
System.out.println(queue.offer("bbb")); // true
System.out.println(queue.offer("ccc")); // true

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

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

System.out.println(queue.peek()); // bbb
System.out.println(queue); // [bbb, ccc]

System.out.println(queue.poll()); // bbb
System.out.println(queue); // [ccc]

System.out.println(queue.peek()); // ccc
System.out.println(queue); // [ccc]

System.out.println(queue.poll()); // ccc
System.out.println(queue); // []

System.out.println(queue.peek()); // null
System.out.println(queue); // []

E poll ()

Retrieves and removes the head of this queue, or returns null if this queue is empty.

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

System.out.println(queue.offer("aaa")); // true
System.out.println(queue.offer("bbb")); // true
System.out.println(queue.offer("ccc")); // true

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

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

System.out.println(queue.poll()); // bbb
System.out.println(queue); // [ccc]

System.out.println(queue.poll()); // ccc
System.out.println(queue); // []

System.out.println(queue.poll()); // null
System.out.println(queue); // []

boolean remove (Object o)

Removes a single instance of the specified element from this queue, if it is present.

final var queue = new PriorityQueue<String>();

System.out.println(queue.offer("aaa")); // true
System.out.println(queue.offer("aaa")); // true
System.out.println(queue.offer("bbb")); // true
System.out.println(queue.offer("bbb")); // true
System.out.println(queue.offer("ccc")); // true

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

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

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

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

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

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 queue = new PriorityQueue<>(src);
    System.out.println(queue); // [A, a, B, b, b, a]

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

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

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

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

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

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

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

boolean removeIf (Predicate<? super E> filter)

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

final var queue = new PriorityQueue<String>();

System.out.println(queue.offer("aaa")); // true
System.out.println(queue.offer("BBB")); // true
System.out.println(queue.offer("ccc")); // true
System.out.println(queue.offer("DDD")); // true

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

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

System.out.println(ret); // true
System.out.println(queue); // [aaa, ccc]

final var queue = new PriorityQueue<String>();

System.out.println(queue.offer("aaa")); // true
System.out.println(queue.offer("bbb")); // true

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

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

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

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 queue = new PriorityQueue<>(src);
    System.out.println(queue); // [A, a, B, b, b, a]

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

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

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

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

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

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

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

int size ()

Returns the number of elements in this collection.

final var queue = new PriorityQueue<String>();

System.out.println(queue); // []
System.out.println(queue.size()); // 0

System.out.println(queue.offer("aaa")); // true

System.out.println(queue); // [aaa]
System.out.println(queue.size()); // 1

System.out.println(queue.offer("bbb")); // true

System.out.println(queue); // [aaa, bbb]
System.out.println(queue.size()); // 2

System.out.println(queue.offer("ccc")); // true

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

queue.clear();

System.out.println(queue); // []
System.out.println(queue.size()); // 0

final Spliterator<E> spliterator ()

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

final var queue = new PriorityQueue<String>();

System.out.println(queue.offer("aaa")); // true
System.out.println(queue.offer("bbb")); // true
System.out.println(queue.offer("ccc")); // true

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

final var spliterator = queue.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 queue.

final var queue = new PriorityQueue<String>();

System.out.println(queue.offer("a")); // true
System.out.println(queue.offer("b")); // true
System.out.println(queue.offer("c")); // true

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

final Object[] array = queue.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 queue; the runtime type of the returned array is that of the specified array.

final var queue = new PriorityQueue<String>();

System.out.println(queue.offer("a")); // true
System.out.println(queue.offer("b")); // true
System.out.println(queue.offer("c")); // true

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

final String[] array = queue.toArray(new String[0]);
System.out.println(Arrays.toString(array)); // [a, b, c]

final var queue = new PriorityQueue<String>();

System.out.println(queue.offer("a")); // true
System.out.println(queue.offer("b")); // true
System.out.println(queue.offer("c")); // true

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

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

    final var ret = queue.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 = queue.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 = queue.toArray(array);
    System.out.println(Arrays.toString(array)); // [null]
    System.out.println(Arrays.toString(ret)); // [a, b, c]
}

Methods declared in AbstractQueue

addAll, element, remove

Please see the link below.

Java API Examples : AbstractQueue

Methods declared in AbstractCollection

containsAll, isEmpty, toString

Please see the link below.

Java API Examples : AbstractCollection

Methods declared in Collection

containsAll, equals, hashCode, isEmpty, parallelStream, stream, toArray

Please see the link below.

Java API Examples : Collection

API Examples

Java : PriorityQueue with Examples

Summary

Constructors

PriorityQueue ()

PriorityQueue (int initialCapacity)

PriorityQueue (int initialCapacity, Comparator<? super E> comparator)

PriorityQueue (Collection<? extends E> c)

PriorityQueue (Comparator<? super E> comparator)

PriorityQueue (PriorityQueue<? extends E> c)

PriorityQueue (SortedSet<? extends E> c)

Methods

boolean add (E e)

void clear ()

Comparator<? super E> comparator ()

boolean contains (Object o)

void forEach (Consumer<? super E> action)

Iterator<E> iterator ()

boolean offer (E e)

E peek ()

E poll ()

boolean remove (Object o)

boolean removeAll (Collection<?> c)

boolean removeIf (Predicate<? super E> filter)

boolean retainAll (Collection<?> c)

int size ()

final Spliterator<E> spliterator ()

Object[] toArray ()

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

Methods declared in AbstractQueue

addAll, element, remove

Methods declared in AbstractCollection

containsAll, isEmpty, toString

Methods declared in Collection

containsAll, equals, hashCode, isEmpty, parallelStream, stream, toArray

Related posts