模块 java.base
包 java.util

类 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 ）。

此队列的 head 是关于指定排序的 least 元素。如果多个元素为最小值绑定，则头部是这些元素之一——任意打破绑定。队列检索操作 poll、remove、peek 和 element 访问队列头部的元素。

优先级队列是无界的，但有一个内部capacity管理用于存储队列中元素的数组的大小。它总是至少与队列大小一样大。随着元素被添加到优先级队列中，其容量会自动增长。增长策略的细节没有具体说明。

此类及其迭代器实现了 Collection 和 Iterator 接口的所有 optional 方法。方法 iterator() 中提供的迭代器和方法 spliterator() 中提供的 Spliterator not 保证以任何特定顺序遍历优先级队列的元素。如果您需要有序遍历，请考虑使用 Arrays.sort(pq.toArray()) 。

请注意，此实现不是同步的。 如果任何线程修改队列，多个线程不应同时访问 PriorityQueue 实例。相反，使用线程安全的 PriorityBlockingQueue 类。

实施说明：此实施为入队和出队方法（offer、poll、remove() 和add）提供了 O(log(n)) 时间； remove(Object) 和 contains(Object) 方法的线性时间；和检索方法的常数时间（peek、element 和 size）。

此类是 Java 集合框架 的成员。

自从：
1.5
参见：

  • 构造方法详细信息

    • PriorityQueue

      public PriorityQueue()
      创建一个具有默认初始容量 (11) 的 PriorityQueue，根据它们的 自然排序 对其元素进行排序。

    • 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 - 如果指定的集合或其任何元素为空

    • PriorityQueue

      public PriorityQueue(PriorityQueue <? extends E > c)
      创建一个包含指定优先级队列中元素的PriorityQueue。该优先级队列将按照与给定优先级队列相同的顺序进行排序。
      参数：
      c - 其元素要放入此优先级队列的优先级队列
      抛出：
      ClassCastException - 如果 c 的元素不能根据 c 的顺序相互比较
      NullPointerException - 如果指定的优先级队列或其任何元素为空

    • PriorityQueue

      public PriorityQueue(SortedSet <? extends E > c)
      创建一个 PriorityQueue 包含指定排序集中的元素。该优先级队列将按照与给定排序集相同的顺序进行排序。
      参数：
      c - 其元素要放入此优先级队列的有序集合
      抛出：
      ClassCastException - 如果指定的有序集合的元素不能根据有序集合的顺序相互比较
      NullPointerException - 如果指定的排序集或其任何元素为空

  • 方法详情

    • add

      public boolean add(E  e)
      将指定元素插入此优先级队列。
      指定者：
      add 在接口 Collection<E> 中
      指定者：
      add 在接口 Queue<E> 中
      重写：
      add 在类 AbstractQueue<E> 中
      参数：
      e - 要添加的元素
      返回：
      true（由 Collection.add(E) 指定）
      抛出：
      ClassCastException - 如果根据优先级队列的顺序无法将指定元素与当前在此优先级队列中的元素进行比较
      NullPointerException - 如果指定元素为空

    • offer

      public boolean offer(E  e)
      将指定元素插入此优先级队列。
      指定者：
      offer 在接口 Queue<E> 中
      参数：
      e - 要添加的元素
      返回：
      true（由 Queue.offer(E) 指定）
      抛出：
      ClassCastException - 如果根据优先级队列的顺序无法将指定元素与当前在此优先级队列中的元素进行比较
      NullPointerException - 如果指定元素为空

    • 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 之间的桥梁。

      指定者：
      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() 相同。
      指定者：
      toArray 在接口 Collection<E> 中
      重写：
      toArray 在类 AbstractCollection<E> 中
      类型参数：
      T - 包含集合的数组的组件类型
      参数：
      a - 要存储队列元素的数组，如果它足够大的话；否则，为此分配一个相同运行时类型的新数组。
      返回：
      包含此队列中所有元素的数组
      抛出：
      ArrayStoreException - 如果指定数组的运行时类型不是此队列中每个元素的运行时类型的超类型
      NullPointerException - 如果指定数组为空

    • iterator

      public Iterator <E > iterator()
      返回此队列中元素的迭代器。迭代器不会以任何特定顺序返回元素。
      指定者：
      iterator 在接口 Collection<E> 中
      指定者：
      iterator 在接口 Iterable<E> 中
      指定者：
      iterator 在类 AbstractCollection<E> 中
      返回：
      此队列中元素的迭代器

    • size

      public int size()
      从接口 Collection 复制的描述
      返回此集合中的元素数。如果此集合包含超过 Integer.MAX_VALUE 个元素，则返回 Integer.MAX_VALUE 。
      指定者：
      size 在接口 Collection<E> 中
      返回：
      此集合中的元素数

    • clear

      public void clear()
      从此优先级队列中删除所有元素。此调用返回后队列将为空。
      指定者：
      clear 在接口 Collection<E> 中
      重写：
      clear 在类 AbstractQueue<E> 中

    • poll

      public E  poll()
      从接口 Queue 复制的描述
      检索并删除此队列的头部，如果此队列为空，则返回 null。
      指定者：
      poll 在接口 Queue<E> 中
      返回：
      此队列的头部，或 null 如果此队列为空

    • comparator

      public Comparator <? super E > comparator()
      返回用于对该队列中的元素进行排序的比较器，如果该队列是根据其元素的 自然排序 排序的，则返回 null。
      返回：
      用于排序此队列的比较器，或者 null 如果此队列是根据其元素的自然顺序排序的

    • spliterator

      public final Spliterator <E > spliterator()
      在此队列中的元素上创建 late-binding 和 fail-fast Spliterator 。拆分器不会以任何特定顺序遍历元素（未报告 ORDERED 特性）。

      Spliterator 报告 Spliterator.SIZED 、Spliterator.SUBSIZED 和 Spliterator.NONNULL 。覆盖实施应记录附加特征值的报告。

      指定者：
      spliterator 在接口 Collection<E> 中
      指定者：
      spliterator 在接口 Iterable<E> 中
      返回：
      a Spliterator 遍历此队列中的元素
      自从：
      1.8

    • removeIf

      public boolean removeIf(Predicate <? super E > filter)
      从接口 Collection 复制的描述
      移除此集合中满足给定谓词的所有元素。迭代期间或由谓词抛出的错误或运行时异常将传递给调用者。
      指定者：
      removeIf 在接口 Collection<E> 中
      参数：
      filter - 为要删除的元素返回 true 的谓词
      返回：
      true 如果删除了任何元素
      抛出：
      NullPointerException - 如果指定的过滤器为空

    • removeAll

      public boolean removeAll(Collection <?> c)
      从类复制的描述：AbstractCollection
      删除此集合的所有也包含在指定集合中的元素（可选操作）。此调用返回后，此集合将不包含与指定集合共有的元素。
      指定者：
      removeAll 在接口 Collection<E> 中
      重写：
      removeAll 在类 AbstractCollection<E> 中
      参数：
      c - 包含要从此集合中删除的元素的集合
      返回：
      true 如果此集合因调用而更改
      抛出：
      NullPointerException - 如果此集合包含一个或多个空元素并且指定的集合不支持空元素 (optional)，或者如果指定的集合为空
      参见：

    • retainAll

      public boolean retainAll(Collection <?> c)
      从类复制的描述：AbstractCollection
      仅保留此集合中包含在指定集合中的元素（可选操作）。换句话说，从该集合中移除所有未包含在指定集合中的元素。
      指定者：
      retainAll 在接口 Collection<E> 中
      重写：
      retainAll 在类 AbstractCollection<E> 中
      参数：
      c - 包含要保留在此集合中的元素的集合
      返回：
      true 如果此集合因调用而更改
      抛出：
      NullPointerException - 如果此集合包含一个或多个空元素并且指定的集合不允许空元素 (optional)，或者如果指定的集合为空
      参见：

    • forEach

      public void forEach(Consumer <? super E > action)
      从接口 Iterable 复制的描述
      对 Iterable 的每个元素执行给定的操作，直到处理完所有元素或操作引发异常。如果指定了迭代顺序，则将按迭代顺序执行操作。操作抛出的异常被转发给调用者。

      如果操作执行修改元素的底层源的副作用，则此方法的行为是未指定的，除非重写类已指定并发修改策略。

      指定者：
      forEach 在接口 Iterable<E> 中
      参数：
      action - 对每个元素执行的操作
      抛出：
      NullPointerException - 如果指定的操作为空