LongValuesCursor (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.document.column, class: LongValuesCursor

Package org.apache.lucene.document.column

# Class LongValuesCursor

java.lang.Object
org.apache.lucene.document.column.LongValuesCursor

public abstract class LongValuesCursor extends Object
A values cursor over a dense `LongColumn`. The cursor produces exactly `size()` values for consecutive batch-local doc-ids starting at 0, one per call to `nextLong()`.

Implementations must throw an exception if `nextLong()` is called more than `size()` times.

WARNING: This API is experimental and might change in incompatible ways in the next release.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `LongValuesCursor(int size)`
  Creates a cursor that will produce exactly `size` values, one per batch-local doc-id in `[0, size)`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `fillDocValues(long[] dst, int offset, int length)`
  Bulk-fill `length` values into `dst` starting at `offset`, advancing the cursor by `length`.
  `void`
  `fillIntPoints(byte[] dst, int offset, int length)`
  Bulk-encode `length` values as 4-byte big-endian sortable int points (sign-flipped so negatives sort before positives) into `dst` starting at byte `offset`, advancing the cursor by `length`.
  `void`
  `fillLongPoints(byte[] dst, int offset, int length)`
  Bulk-encode `length` values as 8-byte big-endian sortable long points (sign-flipped so negatives sort before positives) into `dst` starting at byte `offset`, advancing the cursor by `length`.
  `abstract long`
  `nextLong()`
  Returns the next long value.
  `final int`
  `size()`
  Total number of values this cursor will produce.

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

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

- ## Constructor Details

  - ### LongValuesCursor

    protected LongValuesCursor(int size)
    Creates a cursor that will produce exactly `size` values, one per batch-local doc-id in `[0, size)`. `size` is fixed for the cursor's lifetime and must equal the dense column's `numDocs`.

    Lucene's internal indexing paths will not consume past `size` across `nextLong()`, `fillDocValues(long[], int, int)`, and the `fillPoints` variants. Defensive throws on overrun are still encouraged to catch misuse from external callers.

- ## Method Details

  - ### size

    public final int size()
    Total number of values this cursor will produce.

  - ### nextLong

    public abstract long nextLong()
    Returns the next long value. Must not be called more than `size()` times.

  - ### fillDocValues

    public void fillDocValues(long[] dst, int offset, int length)
    Bulk-fill `length` values into `dst` starting at `offset`, advancing the cursor by `length`. Combined `nextLong()` and `fill` calls must not consume more than `size()` values; implementations must throw if they do.

    The default implementation calls `nextLong()` in a loop. Override to provide a more efficient bulk fill (for example a `System.arraycopy(java.lang.Object, int, java.lang.Object, int, int)` from a backing array).

  - ### fillLongPoints

    public void fillLongPoints(byte[] dst, int offset, int length)
    Bulk-encode `length` values as 8-byte big-endian sortable long points (sign-flipped so negatives sort before positives) into `dst` starting at byte `offset`, advancing the cursor by `length`. Combined consumption across `nextLong()`, `fillDocValues(long[], int, int)`, and the `fillPoints` variants must not exceed `size()`.

    Values are read in doc-values orientation: callers using this for `DOUBLE` columns are responsible for ensuring the cursor's longs are already `sortable-long` encoded, which is the documented `LongColumn` contract.

    The default implementation calls `nextLong()` per value. Override for a tight indexable loop over a backing array.

  - ### fillIntPoints

    public void fillIntPoints(byte[] dst, int offset, int length)
    Bulk-encode `length` values as 4-byte big-endian sortable int points (sign-flipped so negatives sort before positives) into `dst` starting at byte `offset`, advancing the cursor by `length`. Each value is narrowed via `(int) nextLong()`. Combined consumption across `nextLong()`, `fillDocValues(long[], int, int)`, and the `fillPoints` variants must not exceed `size()`.

    Values are read in doc-values orientation: callers using this for `FLOAT` columns are responsible for ensuring the cursor's longs are already `sortable-int` encoded (in the low 32 bits), which is the documented `LongColumn` contract.

    The default implementation calls `nextLong()` per value. Override for a tight indexable loop over a backing array.