Class MinMaxPriorityQueue<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractQueue<E>
cloud.opencode.base.collections.specialized.MinMaxPriorityQueue<E>
Type Parameters:
E - element type | 元素类型
All Implemented Interfaces:
Serializable, Iterable<E>, Collection<E>, Queue<E>
public final class MinMaxPriorityQueue<E> extends AbstractQueue<E> implements Serializable
MinMaxPriorityQueue - Double-ended Priority Queue MinMaxPriorityQueue - 双端优先队列

A priority queue that supports efficient access to both the minimum and maximum elements. Based on a min-max heap data structure.

支持高效访问最小和最大元素的优先队列。基于最小-最大堆数据结构。

Features | 主要功能:

  • Efficient min/max access - O(1) peekFirst/peekLast - 高效最小/最大访问
  • Optional capacity bound - 可选容量限制
  • Auto-eviction when bounded - 有界时自动淘汰
  • Custom comparator support - 自定义比较器支持

Usage Examples | 使用示例:

// Create unbounded queue | 创建无界队列
MinMaxPriorityQueue<Integer> queue = MinMaxPriorityQueue.create();
queue.addAll(Arrays.asList(5, 2, 8, 1, 9, 3));

queue.peekFirst();  // 1 (minimum)
queue.peekLast();   // 9 (maximum)

queue.pollFirst();  // removes 1
queue.pollLast();   // removes 9

// Create bounded queue (keeps N smallest) | 创建有界队列（保留N个最小值）
MinMaxPriorityQueue<Integer> bounded = MinMaxPriorityQueue.<Integer>builder()
    .maximumSize(3)
    .create();
bounded.addAll(Arrays.asList(5, 2, 8, 1, 9));
// Contains: [1, 2, 5] - largest values evicted

// With custom comparator | 使用自定义比较器
MinMaxPriorityQueue<String> byLength = MinMaxPriorityQueue.<String>builder()
    .comparator(Comparator.comparingInt(String::length))
    .maximumSize(5)
    .create();

Performance | 性能特性:

  • add/offer: O(log n) - add/offer: O(log n)
  • peekFirst/peekLast: O(1) - peekFirst/peekLast: O(1)
  • pollFirst/pollLast: O(log n) - pollFirst/pollLast: O(log n)
  • remove: O(n) - remove: O(n)

Thread Safety | 线程安全:

This class is NOT thread-safe. External synchronization is required for concurrent access.

此类非线程安全。并发访问需要外部同步。

Since:
JDK 25, opencode-base-collections V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • create

      public static <E extends Comparable<? super E>> MinMaxPriorityQueue<E> create()
      Create an unbounded MinMaxPriorityQueue using natural ordering. 使用自然顺序创建无界 MinMaxPriorityQueue。
      Type Parameters:
      E - element type (must be Comparable) | 元素类型（必须是 Comparable）
      Returns:
      new empty MinMaxPriorityQueue | 新空 MinMaxPriorityQueue

    • create

      public static <E extends Comparable<? super E>> MinMaxPriorityQueue<E> create(Collection<? extends E> collection)
      Create an unbounded MinMaxPriorityQueue from collection. 从集合创建无界 MinMaxPriorityQueue。
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      collection - the collection | 集合
      Returns:
      new MinMaxPriorityQueue | 新 MinMaxPriorityQueue

    • builder

      public static <E> MinMaxPriorityQueue.Builder<E> builder()
      Create a builder for customized MinMaxPriorityQueue. 创建自定义 MinMaxPriorityQueue 的构建器。
      Type Parameters:
      E - element type | 元素类型
      Returns:
      new builder | 新构建器

    • orderedBy

      public static <E> MinMaxPriorityQueue.Builder<E> orderedBy(Comparator<? super E> comparator)
      Create a builder with specified comparator. 使用指定比较器创建构建器。
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      comparator - the comparator | 比较器
      Returns:
      new builder | 新构建器

    • maximumSize

      public static <E> MinMaxPriorityQueue.Builder<E> maximumSize(int maximumSize)
      Create a bounded queue that keeps the smallest N elements. 创建保留最小 N 个元素的有界队列。
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      maximumSize - maximum size | 最大容量
      Returns:
      new builder | 新构建器

    • peekFirst

      public E peekFirst()
      Returns the smallest element without removing it. 返回最小元素但不移除。
      Returns:
      the smallest element, or null if empty | 最小元素，如果为空则返回 null

    • peekLast

      public E peekLast()
      Returns the largest element without removing it. 返回最大元素但不移除。
      Returns:
      the largest element, or null if empty | 最大元素，如果为空则返回 null

    • pollFirst

      public E pollFirst()
      Removes and returns the smallest element. 移除并返回最小元素。
      Returns:
      the smallest element, or null if empty | 最小元素，如果为空则返回 null

    • pollLast

      public E pollLast()
      Removes and returns the largest element. 移除并返回最大元素。
      Returns:
      the largest element, or null if empty | 最大元素，如果为空则返回 null

    • removeFirst

      public E removeFirst()
      Removes and returns the smallest element, throwing if empty. 移除并返回最小元素，如果为空则抛出异常。
      Returns:
      the smallest element | 最小元素
      Throws:
      NoSuchElementException - if empty | 如果为空

    • removeLast

      public E removeLast()
      Removes and returns the largest element, throwing if empty. 移除并返回最大元素，如果为空则抛出异常。
      Returns:
      the largest element | 最大元素
      Throws:
      NoSuchElementException - if empty | 如果为空

    • offer

      public boolean offer(E e)
      Specified by:
      offer in interface Queue<E>

    • poll

      public E poll()
      Specified by:
      poll in interface Queue<E>

    • peek

      public E peek()
      Specified by:
      peek in interface Queue<E>

    • size

      public int size()
      Specified by:
      size in interface Collection<E>
      Specified by:
      size in class AbstractCollection<E>

    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface Collection<E>
      Overrides:
      isEmpty in class AbstractCollection<E>

    • clear

      public void clear()
      Specified by:
      clear in interface Collection<E>
      Overrides:
      clear in class AbstractQueue<E>

    • 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>

    • maximumSize

      public int maximumSize()
      Returns the maximum size of this queue, or Integer.MAX_VALUE if unbounded. 返回此队列的最大容量，如果无界则返回 Integer.MAX_VALUE。
      Returns:
      maximum size | 最大容量

    • isBounded

      public boolean isBounded()
      Returns true if this queue is bounded. 如果此队列有界，则返回 true。
      Returns:
      true if bounded | 如果有界则返回 true