Класс PriorityQueue<E>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractQueue<E>

java.util.PriorityQueue<E>

Параметры типа:: E - тип элементов, хранящихся в этой очереди

Все реализованные интерфейсы:: Serializable, Iterable<E>, Collection<E>, Queue<E>

public class PriorityQueue<E> extends AbstractQueue<E> implements Serializable

Неограниченная приоритетная очередь, основанная на куче приоритетов. Элементы очереди приоритетов упорядочены в соответствии с их естественным порядком или с помощью Comparator, заданного при создании очереди, в зависимости от используемого конструктора. Очередь приоритетов не допускает null элементов. Очередь приоритетов, использующая естественный порядок, также не допускает вставки несопоставимых объектов (это может привести к ClassCastException).

Голова этой очереди — это наименьший элемент с точки зрения заданного порядка. Если несколько элементов имеют одинаковое наименьшее значение, голова — один из этих элементов; связи разрываются произвольно. Операции получения из очереди poll, remove, peek и element обращаются к элементу в голове очереди.

Очередь приоритетов неограничена, но имеет внутреннюю емкость, определяющую размер массива, используемого для хранения элементов в очереди. Она всегда не меньше размера очереди. По мере добавления элементов в очередь приоритетов её емкость автоматически увеличивается. Подробности политики роста не заданы.

Этот класс и его итератор реализуют все необязательные методы интерфейсов Collection и Iterator. Итератор, предоставляемый в методе iterator(), и разделитель, предоставляемый в методе spliterator(), не гарантируют прохождения элементов очереди приоритетов в каком-либо определенном порядке. Если вам нужен упорядоченный проход, рассмотрите использование Arrays.sort(pq.toArray()).

Обратите внимание, что эта реализация не синхронизирована. Несколько потоков не должны одновременно обращаться к экземпляру PriorityQueue, если какой-либо из потоков изменяет очередь. Вместо этого используйте потокобезопасный класс PriorityBlockingQueue.

Примечание к реализации: эта реализация обеспечивает время O(log(n)) для методов добавления и удаления из очереди (offer, poll, remove() и add); линейное время для методов remove(Object) и contains(Object); и постоянное время для методов извлечения (peek, element и size).

Этот класс является членом Java Collections Framework.

Since:

1.5

См. также:

Краткое описание конструкторов

Конструктор	Описание
`PriorityQueue()`	Создаёт очередь приоритетов с начальной емкостью по умолчанию (11), упорядочивая элементы в соответствии с их естественным порядком.
`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)`	Создаёт очередь приоритетов, содержащую элементы в заданном упорядоченном множестве.

Краткое описание методов

Модификатор и тип	Метод	Описание
`boolean`	`add(E e)`	Вставляет указанный элемент в эту очередь приоритетов.
`void`	`clear()`	Удаляет все элементы из этой очереди приоритетов.
`Comparator<? super E>`	`comparator()`	Возвращает компаратор, используемый для упорядочивания элементов в этой очереди, или `null`, если эта очередь упорядочена в соответствии с естественным порядком своих элементов.
`boolean`	`contains(Object o)`	Возвращает `true`, если эта очередь содержит указанный элемент.
`void`	`forEach(Consumer<? super E> action)`	Выполняет заданное действие для каждого элемента `Iterable`, пока все элементы не будут обработаны или действие не вызовет исключение.
`Iterator<E>`	`iterator()`	Возвращает итератор по элементам в этой очереди.
`boolean`	`offer(E e)`	Вставляет указанный элемент в эту очередь приоритетов.
`E`	`peek()`	Возвращает голову этой очереди, но не удаляет её, или возвращает `null`, если эта очередь пуста.
`E`	`poll()`	Возвращает и удаляет голову этой очереди, или возвращает `null`, если эта очередь пуста.
`boolean`	`remove(Object o)`	Удаляет единственный экземпляр указанного элемента из этой очереди, если он присутствует.
`boolean`	`removeAll(Collection<?> c)`	Удаляет все элементы этой коллекции, которые также содержатся в указанной коллекции (необязательная операция).
`boolean`	`removeIf(Predicate<? super E> filter)`	Удаляет все элементы этой коллекции, удовлетворяющие заданному предикату (необязательная операция).
`boolean`	`retainAll(Collection<?> c)`	Оставляет только элементы в этой коллекции, которые содержатся в указанной коллекции (необязательная операция).
`int`	`size()`	Возвращает количество элементов в этой коллекции.
`final Spliterator<E>`	`spliterator()`	Создаёт позднее связывание и быстрое завершение `Spliterator` по элементам в этой очереди.
`Object[]`	`toArray()`	Возвращает массив, содержащий все элементы в этой очереди.
`<T> T[]`	`toArray(T[] a)`	Возвращает массив, содержащий все элементы в этой очереди; тип возвращаемого массива соответствует заданному массиву.

Методы, объявленные в классе java.util.AbstractQueue

addAll, element, remove

Методы, объявленные в классе java.util.AbstractCollection

containsAll, isEmpty, toString

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Методы, объявленные в интерфейсе java.util.Collection

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

Подробное описание конструкторов

PriorityQueue

public PriorityQueue()

Создаёт PriorityQueue с начальной ёмкостью по умолчанию (11), сортируя элементы по их естественному порядку.

PriorityQueue

public PriorityQueue(int initialCapacity)

Создаёт PriorityQueue с заданной начальной ёмкостью, сортируя элементы по их естественному порядку.

Параметры:: initialCapacity - начальная ёмкость для этой очереди с приоритетами
Исключения:: IllegalArgumentException - если initialCapacity меньше 1

PriorityQueue

public PriorityQueue(Comparator<? super E> comparator)

Создаёт PriorityQueue с начальной ёмкостью по умолчанию, элементы которой упорядочены в соответствии с указанным компаратором.

Параметры:: comparator - компаратор, который будет использоваться для упорядочения этой очереди с приоритетами. Если null, будет использован естественный порядок элементов.
С:: 1.8

PriorityQueue

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

Создаёт PriorityQueue с заданной начальной ёмкостью, элементы которой упорядочены в соответствии с указанным компаратором.

Параметры:: initialCapacity - начальная ёмкость для этой очереди с приоритетами; comparator - компаратор, который будет использоваться для упорядочения этой очереди с приоритетами. Если null, будет использован естественный порядок элементов.
Исключения:: IllegalArgumentException - если initialCapacity меньше 1

PriorityQueue

public PriorityQueue(Collection<? extends E> c)

Создаёт PriorityQueue, содержащую элементы из указанной коллекции. Если указанная коллекция является экземпляром класса SortedSet или другой PriorityQueue, эта очередь с приоритетами будет упорядочена в соответствии с тем же порядком. В противном случае эта очередь с приоритетами будет упорядочена в соответствии с естественным порядком элементов.

Параметры:: c - коллекция, элементы которой должны быть помещены в эту очередь с приоритетами
Исключения:: ClassCastException - если элементы указанной коллекции не могут быть сравнены друг с другом в соответствии с порядком очереди с приоритетами; NullPointerException - если указанная коллекция или любой из её элементов равны null

PriorityQueue

public PriorityQueue(PriorityQueue<? extends E> c)

Создаёт PriorityQueue, содержащую элементы из указанной очереди с приоритетами. Эта очередь с приоритетами будет упорядочена в соответствии с тем же порядком, что и заданная очередь с приоритетами.

Параметры:: c - очередь с приоритетами, элементы которой должны быть помещены в эту очередь с приоритетами
Исключения:: ClassCastException - если элементы c не могут быть сравнены друг с другом в соответствии с порядком c; NullPointerException - если указанная очередь с приоритетами или любой из её элементов равны null

PriorityQueue

public PriorityQueue(SortedSet<? extends E> c)

Создаёт PriorityQueue, содержащую элементы из указанного упорядоченного набора. Эта очередь с приоритетами будет упорядочена в соответствии с тем же порядком, что и заданный упорядоченный набор.

Параметры:: c - упорядоченный набор, элементы которого должны быть помещены в эту очередь с приоритетами
Исключения:: ClassCastException - если элементы указанного упорядоченного набора не могут быть сравнены друг с другом в соответствии с порядком упорядоченного набора; NullPointerException - если указанный упорядоченный набор или любой из его элементов равны null

Подробное описание методов

add

public boolean add(E e)

Вставляет указанный элемент в эту очередь с приоритетами.

Унаследованно от:: add в интерфейсе Collection<E>
Унаследованно от:: add в интерфейсе Queue<E>
Переопределяет:: add в классе AbstractQueue<E>
Параметры:: e - элемент для добавления
Возвращает:: true (как указано в Collection.add(E))
Исключения:: ClassCastException - если указанный элемент не может быть сравнен с текущими элементами в этой очереди с приоритетами в соответствии с порядком очереди; NullPointerException - если указанный элемент равен null

offer

public boolean offer(E e)

Вставляет указанный элемент в эту очередь с приоритетами.

Унаследованно от:: offer в интерфейсе Queue<E>
Параметры:: e - элемент для добавления
Возвращает:: true (как указано в Queue.offer(E))
Исключения:: ClassCastException - если указанный элемент не может быть сравнен с текущими элементами в этой очереди с приоритетами в соответствии с порядком очереди; NullPointerException - если указанный элемент равен null

peek

public E peek()

Описание скопировано из интерфейса: Queue

Извлекает, но не удаляет, голову этой очереди или возвращает null, если эта очередь пуста.

Унаследованно от:: peek в интерфейсе Queue<E>
Возвращает:: голову этой очереди или null, если эта очередь пуста

remove

public boolean remove(Object o)

Удаляет единственный экземпляр указанного элемента из этой очереди, если он присутствует. Более формально, удаляет элемент e такой, что o.equals(e), если эта очередь содержит один или несколько таких элементов. Возвращает true тогда и только тогда, когда эта очередь содержала указанный элемент (или, что эквивалентно, если эта очередь изменилась в результате вызова).

Унаследованно от:: remove в интерфейсе Collection<E>
Переопределяет:: remove в классе AbstractCollection<E>
Параметры:: o - элемент, который нужно удалить из этой очереди, если он присутствует
Возвращает:: true если эта очередь изменилась в результате вызова

contains

public boolean contains(Object o)

Возвращает true, если эта очередь содержит указанный элемент. Более формально, возвращает true тогда и только тогда, когда эта очередь содержит по крайней мере один элемент e такой, что o.equals(e).

Унаследованно от:: contains в интерфейсе Collection<E>
Переопределяет:: contains в классе AbstractCollection<E>
Параметры:: o - объект, который нужно проверить на содержание в этой очереди
Возвращает:: true если эта очередь содержит указанный элемент

toArray

public Object[] toArray()

Возвращает массив, содержащий все элементы в этой очереди. Элементы не упорядочены каким-либо определённым образом.

Возвращаемый массив будет «безопасным» в том смысле, что на него не ссылается эта очередь. (Другими словами, этот метод должен выделить новый массив). Таким образом, вызывающий метод свободен изменять возвращаемый массив.

Этот метод действует как мост между API, основанным на массивах, и API, основанным на коллекциях.

Унаследованно от:: toArray в интерфейсе Collection<E>
Переопределяет:: toArray в классе AbstractCollection<E>
Возвращает:: массив, содержащий все элементы в этой очереди

toArray

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

Возвращает массив, содержащий все элементы в этой очереди; тип времени выполнения возвращаемого массива — тип указанного массива. Элементы возвращаемого массива расположены в произвольном порядке. Если очередь помещается в указанный массив, она возвращается в нём. В противном случае выделяется новый массив с типом времени выполнения указанного массива и размером этой очереди.

Если очередь помещается в указанный массив с избыточным местом (т.е. массив имеет больше элементов, чем очередь), элемент в массиве непосредственно после конца коллекции устанавливается в null.

Как и метод toArray(), этот метод действует как мост между основанными на массивах и основанными на коллекциях API. Кроме того, этот метод позволяет точно управлять типом времени выполнения выходного массива и может в некоторых случаях использоваться для экономии затрат на выделение памяти.

Предположим, что x — это очередь, известная тем, что содержит только строки. Следующий код можно использовать для выгрузки очереди в новый выделенный массив String:

 String[] y = x.toArray(new String[0]);

Обратите внимание, что toArray(new Object[0]) идентичен по функции toArray().

Specified by:: toArray in interface Collection<E>
Overrides:: toArray in class AbstractCollection<E>
Type Parameters:: T — компонентный тип массива, содержащего коллекцию
Parameters:: a — массив, в который должны быть сохранены элементы очереди, если он достаточно большой; в противном случае для этой цели выделяется новый массив того же типа времени выполнения.
Returns:: массив, содержащий все элементы в этой очереди
Throws:: ArrayStoreException — если тип времени выполнения указанного массива не является надтипом типа времени выполнения каждого элемента в этой очереди; NullPointerException — если указанный массив null

iterator

public Iterator<E> iterator()

Возвращает итератор по элементам в этой очереди. Итератор не возвращает элементы в каком-либо определённом порядке.

Specified by:: iterator in interface Collection<E>
Specified by:: iterator in interface Iterable<E>
Specified by:: iterator in class AbstractCollection<E>
Returns:: итератор по элементам в этой очереди

size

public int size()

Описание скопировано из интерфейса: Collection

Возвращает количество элементов в этой коллекции. Если эта коллекция содержит более Integer.MAX_VALUE элементов, возвращает Integer.MAX_VALUE.

Specified by:: size in interface Collection<E>
Returns:: количество элементов в этой коллекции

clear

public void clear()

Удаляет все элементы из этой очереди приоритетов. Очередь будет пустой после возврата этого вызова.

Specified by:: clear in interface Collection<E>
Overrides:: clear in class AbstractQueue<E>

poll

public E poll()

Описание скопировано из интерфейса: Queue

Возвращает и удаляет голову этой очереди или возвращает null, если эта очередь пуста.

Specified by:: poll in interface Queue<E>
Returns:: голова этой очереди или null, если эта очередь пуста

comparator

public Comparator<? super E> comparator()

Возвращает компаратор, используемый для упорядочивания элементов в этой очереди, или null, если эта очередь отсортирована в соответствии с естественным порядком своих элементов.

Returns:: компаратор, используемый для упорядочения этой очереди, или null, если эта очередь отсортирована в соответствии с естественным порядком своих элементов

spliterator

public final Spliterator<E> spliterator()

Создаёт отложенную привязку и немедленно прекращающий работу Spliterator по элементам в этой очереди. Разделитель не обходит элементы в определённом порядке (характеристика ORDERED не сообщается).

Spliterator сообщает Spliterator.SIZED, Spliterator.SUBSIZED и Spliterator.NONNULL. Реализующие классы должны документировать сообщения об дополнительных характеристиках.

Specified by:: spliterator in interface Collection<E>
Specified by:: spliterator in interface Iterable<E>
Returns:: Spliterator по элементам в этой очереди
Since:: 1.8

removeIf

public boolean removeIf(Predicate<? super E> filter)

Описание скопировано из интерфейса: Collection

Удаляет все элементы этой коллекции, удовлетворяющие заданному предикату (необязательная операция). Ошибки или исключения времени выполнения, выброшенные во время итерации или предикатом, передаются вызывающему методу.

Specified by:: removeIf in interface Collection<E>
Parameters:: filter — предикат, возвращающий true для элементов, которые необходимо удалить
Returns:: true, если какие-либо элементы были удалены
Throws:: NullPointerException — если указанный фильтр null

removeAll

public boolean removeAll(Collection<?> c)

Описание скопировано из класса: AbstractCollection

Удаляет все элементы этой коллекции, которые также содержатся в указанной коллекции (необязательная операция). После возврата этого вызова эта коллекция не будет содержать элементов, общих с указанной коллекцией.

Specified by:

removeAll in interface Collection<E>

Overrides:

removeAll in class AbstractCollection<E>

Parameters:

c — коллекция, содержащая элементы, которые необходимо удалить из этой коллекции

Returns:

true, если эта коллекция изменилась в результате вызова

Throws:

NullPointerException — если эта коллекция содержит один или несколько null-элементов, а указанная коллекция не поддерживает null-элементы (необязательное) или если указанная коллекция null

See Also:

retainAll

public boolean retainAll(Collection<?> c)

Описание скопировано из класса: AbstractCollection

Сохраняет только элементы в этой коллекции, которые содержатся в указанной коллекции (необязательная операция). Другими словами, удаляет из этой коллекции все её элементы, которые не содержатся в указанной коллекции.

Specified by:

retainAll in interface Collection<E>

Overrides:

retainAll in class AbstractCollection<E>

Parameters:

c — коллекция, содержащая элементы, которые необходимо сохранить в этой коллекции

Returns:

true, если эта коллекция изменилась в результате вызова

Throws:

NullPointerException — если эта коллекция содержит один или несколько null-элементов, а указанная коллекция не допускает null-элементов (необязательное) или если указанная коллекция null

See Also:

forEach

public void forEach(Consumer<? super E> action)

Описание скопировано из интерфейса: Iterable

Выполняет данное действие для каждого элемента Iterable, пока все элементы не будут обработаны или действие не выбросит исключение. Действия выполняются в порядке итерации, если этот порядок указан. Исключение, выброшенное действием, передаётся вызывающему методу.

Поведение этого метода не определено, если действие выполняет побочные эффекты, которые изменяют базовый источник элементов, если реализующий класс не указал политику одновременного изменения.

Specified by:: forEach in interface Iterable<E>
Parameters:: action — действие, которое должно выполняться для каждого элемента
Throws:: NullPointerException — если указанное действие null

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://download.java.net/java/early_access/jdk24/docs/api/java.base/java/util/PriorityQueue.html