ddn.columnar.list

The list-column layer of ddn.df (ADR-2026-10-23-13/-14): offset-and-child storage where a null list (validity-0, empty span) is distinct from an empty list (valid, zero span), and child nulls live in the child's own validity. Offsets are int64 counts into the child's visible elements; parents share the sealed child chunk across slices (the sealed-chunk invariant, ADR-2026-10-18-09).

Copyright

License

BSD-3-Clause

struct ListBuilder ListView

fn enforceFlatElement listLengthAt listLengths listRechunk listSeries listTake listViewOf validateListChunk

Types 2

structListBuilder

Builds one LIST chunk: int64 offsets into a sealed child chunk the caller supplies (already gathered/collected). Offsets advance with each appended list; appendNull and appendEmpty both advance by zero, distinguished only by the validity bit - the null-vs-empty contract of ADR-2026-10-23-14.

Fields

private long[] _spans

private ulong[] _validity

private size_t _length

private bool _anyNull

private bool _sealed

Methods

void append(size_t n) @safe pure nothrowAppends a list of `n` elements (the elements are already in the child; only the span records the count).

void appendNull() @safe pure nothrowAppends a null list (zero span, validity-0).

void appendEmpty() @safe pure nothrowAppends an empty list (zero span, valid).

void appendValid(bool valid) @safe pure nothrowAppends a null or empty list directly from a Nullable validity.

void appendSpans(size_t n, bool valid) @safe pure nothrowAppends one list's span and validity together.

private void setValid(size_t i, bool v) @safe pure nothrow

ArrayData finish(DataType element, ArrayData child) @safe pure nothrowSeals the parent chunk over the given child.

private size_t countValid() @safe pure nothrow

structListView

One list slot's view into the child: the element span and its validity.

Fields

ArrayData childThe child chunk holding the elements.

size_t startThe first child element of this list.

size_t lengthThe element count (0 for null and empty lists alike).

Methods

bool isEmpty() const @safe pure nothrow @nogcReturns: `true` when the list has no elements (null or empty).

Functions 9

fnListView listViewOf(const ArrayData chunk, size_t i) @trusted pure nothrowViews list slot `i` of a LIST chunk.

fnvoid validateListChunk(const ArrayData chunk) @safeValidates a LIST chunk's structure: monotone non-negative offsets within the child, the child's dtype matching the metadata.

Series listSeries(string name,  ArrayData child,  size_t[]  spans,
       bool[]  valid)

Builds a LIST Series over a pre-built child chunk, from spans.

Series listSeries(E)(string name,  DataType element,
       Nullable!(E[])[]  values)

Builds a LIST Series from arrays of nullable element arrays, one flat child for the primitive element kinds. Params: name = the Series name element = the element dtype (a primitive kind) ...

fnsize_t listLengthAt(Series s, size_t i) @safe pure nothrowThe list slot's element count (0 for null and empty lists; use isValid on the parent to distinguish).

ArrayData listTake(ArrayData[]  chunks,
       const  size_t[]  chunkStarts,  const(size_t)[]  indices,
       DataType element)

fnSeries listLengths(Series s)

private fnvoid enforceFlatElement(DataType element, string op) @safe

fnArrayData listRechunk(const ArrayData[] chunks, DataType dtype) @trusted