How does PriorityQueue work in EK9?

← Collections and Data Structures · Ref: Q121

EK9 provides a generic PriorityQueue type that maintains elements in sorted order. It supports bounded size for top-N patterns and integrates with stream pipelines.

CREATION

Create a PriorityQueue with an initial element:

  pq <- PriorityQueue("first")

Or create an empty typed queue:

  pq <- PriorityQueue() of String

COMPARATOR SETUP

A PriorityQueue needs a comparator to determine order:

  comparator <- () extends Comparator of String as pure function (r:=? t1 <=> t2)
  pq <- PriorityQueue("Bill").withComparator(comparator)

The comparator is a pure function using the <=> operator.

ADDING ELEMENTS

Use += to add elements:

  pq += "Ted"
  pq += "Excellent"

Elements are automatically maintained in priority order.

BOUNDED QUEUES

Create a bounded queue that keeps only the top N items:

  topThree <- pq.withSize(3)

When more than N elements are added, the lowest-priority element is dropped. This is the efficient top-N pattern.

ACCESSING ORDERED RESULTS

Get elements as a sorted list:

  items <- pq.list()

Or reverse the order:

  reversed <- pq.list().reverse()

STREAM INTEGRATION

Use PriorityQueue as a pipeline terminal:

  cat items | filter by isGood | collect as PriorityQueue of String

Or as a pipeline source:

  cat pq | map with transform > stdout

See Q45 for List basics. See Q120 for sorting. See Q122 for collect as custom aggregation. See Q126 for choosing the right collection type.

Example

defines module qa.collections.priorityqueue

  defines function

    comparingStrings() as pure
      ->
        t1 as String
        t2 as String
      <-
        rtn as Integer: t1 <=> t2

    suitableLength() as pure
      -> item as String
      <- rtn <- Boolean()
      minLength <- 3
      rtn: length item > minLength

  defines program

    PriorityQueueDemo()
      stdout <- Stdout()

      // === CREATION WITH COMPARATOR ===

      comparator <- () extends Comparator of String as pure function (r:=? t1 <=> t2)
      pq <- PriorityQueue("Bill").withComparator(comparator)

      // === ADDING ELEMENTS ===

      pq += "And"
      pq += "Ted"
      pq += "Excellent"
      pq += "Adventure"

      allEntries <- pq.list()
      stdout.println(`All entries: ${allEntries}`)

      // === BOUNDED QUEUE (TOP-N) ===

      topThree <- pq.withSize(3)
      limitedEntries <- topThree.list()
      stdout.println(`Top 3: ${limitedEntries}`)

      // === STREAM AS SOURCE ===

      cat allEntries | filter by suitableLength > stdout

      // === EMPTY QUEUE ===

      emptyQ <- PriorityQueue() of String
      require emptyQ?
      require emptyQ is empty
      stdout.println(`Empty PQ isSet: ${emptyQ?}`)

Common mistakes

E50060 — PriorityQueue does not have a Java-style peek() method. Use .list() to get all entries as a sorted List. See ek9 -h E50060 for details.

Incorrect:

allEntries <- pq.peek()

Correct:

allEntries <- pq.list()

E50060 — PriorityQueue does not have a Java-style toArray() method. Use .list() to get entries as a List. See ek9 -h E50060 for details.

Incorrect:

allEntries <- pq.toArray()

Correct:

allEntries <- pq.list()

E50060 — PriorityQueue does not have a Java-style .add() method. Use the += operator to add elements. See ek9 -h E50060 for details.

Incorrect:

pq.add("Ted")

Correct:

pq += "Ted"

E50060 — EK9 does not have toString(). Use the $ operator or string interpolation. See ek9 -h E50060 for details.

Incorrect:

stdout.println(allEntries.toString())

Correct:

stdout.println(`All entries: ${allEntries}`)

Coming from another language?

Java: PriorityQueue<T> with Comparator, no bounded size built-in (must manage manually). Python: heapq module, heapq.nlargest() for top-N. JavaScript: no built-in priority queue, use libraries. Rust: BinaryHeap<T> with Reverse wrapper. Go: container/heap interface. EK9: PriorityQueue(elem).withComparator(comp).withSize(n) fluent API, integrated with stream pipelines.

Keywords: collect, queue, order, withSize, bounded, sorted, comparator, top, withComparator, data-structure, collection, priority