Module interleave 

The Interleave encoding: a lazy, random-access gather of N value arrays into one array, routed by a per-row (array_index, row_index) pair.

Specification

An Interleave array has N + 2 children: N values followed by an array_indices selector and a row_indices selector. The output has array_indices.len() rows, and output row i comes from values[array_indices[i]][row_indices[i]].

Unlike a Merge, which consumes each branch in order under a cursor, an Interleave is random-access: row_indices names an explicit position within the selected value array, so rows may be reordered, skipped, or repeated. A Merge is the special case where each value array is consumed front-to-back exactly once.

Like a Merge, the value arrays are independent: each holds only its own rows, and the selectors stitch them back together. This distinguishes Interleave from an element-wise select such as zip, whose arguments are all full-length.

Invariants

• Both selectors are non-nullable and equal in length, which is the output length. They record where each output row comes from, which is always a definite decision. Predicate nullability must be resolved into definite indices by the caller before the interleave is built.
• array_indices[i] < values.len() and row_indices[i] < values[array_indices[i]].len() for every i. These per-row bounds depend on the selector values and so are a runtime precondition of the caller, checked in the execution kernels rather than at construction.
• All values share a logical type up to nullability. The output type is that shared type with the union of the values’ nullabilities. This is orthogonal to the selectors: a row’s value may be null even though its (array_index, row_index) is definite.
• The output length equals array_indices.len() (== row_indices.len()).

Selector types

array_indices encodes the value array per row as a non-nullable unsigned integer (array_indices[i] is the index into values). row_indices is likewise a non-nullable unsigned integer naming the position within the selected value array.

Structs

Interleave

The Interleave encoding. See the module docs.

InterleaveData

Per-array metadata for an InterleaveArray.

Traits

InterleaveArrayExt

Accessors for the values and selectors of an InterleaveArray.

Type Aliases

InterleaveArray

An Interleave-encoded Vortex array. See the module docs for the specification.