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

Package org.apache.lucene.document.column

# Class BytesRefValuesCursor

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

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

Implementations must throw an exception if `nextValue()` is called more than `size()` times. The returned `BytesRef` is valid only until the next call to `nextValue()`.

Combined consumption across `nextValue()` and `fillPackedPoints(byte[], int, int, int)` must not exceed `size()`.

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

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `BytesRefValuesCursor(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`
  `fillPackedPoints(byte[] dst, int offset, int length, int width)`
  Bulk-fill `length` fixed-width packed point records into `dst` starting at byte `offset`, advancing the cursor by `length`.
  `abstract BytesRef`
  `nextValue()`
  Returns the next `BytesRef` 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

  - ### BytesRefValuesCursor

    protected BytesRefValuesCursor(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 `nextValue()` and `fillPackedPoints(byte[], int, int, int)`. 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.

  - ### nextValue

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

  - ### fillPackedPoints

    public void fillPackedPoints(byte[] dst, int offset, int length, int width)
    Bulk-fill `length` fixed-width packed point records into `dst` starting at byte `offset`, advancing the cursor by `length`. Each value must be exactly `width` bytes and is passed through unchanged (no sortable encoding). Combined consumption across `nextValue()` and this method must not exceed `size()`.

    The default implementation calls `nextValue()` per value and validates each length. Override when the backing data is optimizable (e.g. a contiguous packed array); such overrides take responsibility for the width contract.