TernaryLongHeap (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.util, class: TernaryLongHeap

Package org.apache.lucene.util

# Class TernaryLongHeap

java.lang.Object
org.apache.lucene.util.TernaryLongHeap

public final class TernaryLongHeap extends Object
A ternary min heap that stores longs; a primitive priority queue that like all priority queues maintains a partial ordering of its elements such that the least element can always be found in constant time. Put()'s and pop()'s require log_3(size). This heap provides unbounded growth via `push(long)`, and bounded-size insertion based on its nominal initial capacity via `insertWithOverflow(long)`. The heap is a min heap, meaning that the top element is the lowest value of the heap. TernaryLongHeap implements 3-ary heap.

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TernaryLongHeap(int initialCapacity)`
  Create an empty priority queue of the configured initial size.
  `TernaryLongHeap(int size, long initialValue)`
  Constructs a heap with specified size and initializes all elements with the given value.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  Removes all entries from the PriorityQueue.
  `long`
  `get(int i)`
  Return the element at the ith location in the heap array.
  `boolean`
  `insertWithOverflow(long value)`
  Adds a value to an TernaryLongHeap in log(size) time.
  `long`
  `pop()`
  Removes and returns the least element of the PriorityQueue in log(size) time.
  `long`
  `push(long element)`
  Adds a value in log(size) time.
  `void`
  `pushAll(TernaryLongHeap other)`
  `int`
  `size()`
  Returns the number of elements currently stored in the PriorityQueue.
  `long`
  `top()`
  Returns the least element of the TernaryLongHeap in constant time.
  `long`
  `updateTop(long value)`
  Replace the top of the pq with `newTop`.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### TernaryLongHeap

    public TernaryLongHeap(int size, long initialValue)
    Constructs a heap with specified size and initializes all elements with the given value.
    Parameters:
      `size` - the number of elements to initialize in the heap.
      `initialValue` - the value to fill the heap with.

  - ### TernaryLongHeap

    public TernaryLongHeap(int initialCapacity)
    Create an empty priority queue of the configured initial size.
    Parameters:
      `initialCapacity` - the initial capacity of the heap

- ## Method Details

  - ### push

    public long push(long element)
    Adds a value in log(size) time. Grows unbounded as needed to accommodate new values.
    Returns:
      the new 'top' element in the queue.

  - ### insertWithOverflow

    public boolean insertWithOverflow(long value)
    Adds a value to an TernaryLongHeap in log(size) time. If the number of values would exceed the heap's initialCapacity, the least value is discarded.
    Returns:
      whether the value was added (unless the heap is full, or the new value is less than the top value)

  - ### top

    public long top()
    Returns the least element of the TernaryLongHeap in constant time. It is up to the caller to verify that the heap is not empty; no checking is done, and if no elements have been added, 0 is returned.

  - ### pop

    public long pop()
    Removes and returns the least element of the PriorityQueue in log(size) time.
    Throws:
      `IllegalStateException` - if the TernaryLongHeap is empty.

  - ### updateTop

    public long updateTop(long value)
    Replace the top of the pq with `newTop`. Should be called when the top value changes. Still log(n) worst case, but it's at least twice as fast to

         pq.updateTop(value);

    instead of

         pq.pop();
         pq.push(value);

    Calling this method on an empty TernaryLongHeap has no visible effect.

    Parameters:
      `value` - the new element that is less than the current top.
    Returns:
      the new 'top' element after shuffling the heap.

  - ### size

    public int size()
    Returns the number of elements currently stored in the PriorityQueue.

  - ### clear

    public void clear()
    Removes all entries from the PriorityQueue.

  - ### pushAll

    public void pushAll(TernaryLongHeap other)

  - ### get

    public long get(int i)
    Return the element at the ith location in the heap array. Use for iterating over elements when the order doesn't matter. Note that the valid arguments range from [1, size].