Struct VarBinViewBuilder 

pub struct VarBinViewBuilder { /* private fields */ }

The builder for building a VarBinViewArray.

Implementations

impl VarBinViewBuilder

pub fn with_capacity(dtype: DType, capacity: usize) -> Self

pub fn with_buffer_deduplication(dtype: DType, capacity: usize) -> Self

pub fn with_compaction( dtype: DType, capacity: usize, compaction_threshold: f64, ) -> Self

pub fn new( dtype: DType, capacity: usize, completed: CompletedBuffers, growth_strategy: BufferGrowthStrategy, compaction_threshold: f64, ) -> Self

pub fn append_value<S: AsRef<[u8]>>(&mut self, value: S)

Appends a value to the builder.

pub fn append_n_values<S: AsRef<[u8]>>(&mut self, value: S, n: usize)

Appends n copies of value as non-null entries.

pub fn completed_block_count(&self) -> u32

pub fn append_views_built_at( &mut self, validity: &Mask, build: impl FnOnce(u32) -> VortexResult<(Vec<ByteBuffer>, Buffer<BinaryView>)>, ) -> VortexResult<()>

Adopts the buffers and views that build produces against the index its first buffer will land at.

The builder flushes its staged bytes, then hands build the index the next data buffer will occupy; build returns data buffers — which land contiguously from that index — and one view per entry of validity, already referencing them. This is the escape hatch for an encoding that only discovers its views while walking its own byte format (e.g. length-prefixed frames), where the lengths-driven appends cannot apply; keeping the numbering inside this call is what makes the views come out right without a rebase pass.

Warning

This method does not check utilization of the returned buffers. build must return buffers that are fully utilized by its views.

Panics

Panics if build returns a different view count than validity.len(), or if this builder deduplicates buffers and already holds one of the returned buffers.

pub fn append_views_gathered( &mut self, buffers: impl IntoIterator<Item = ByteBuffer>, views: &[BinaryView], validity: &Mask, view_at: impl Fn(usize) -> usize, )

Appends validity.len() values, gathering each valid row’s view from views through the index view_at returns for it.

buffers — the data buffers the views reference, in the numbering the views use — are adopted through the builder’s buffer storage, and every gathered view is rebased onto the indices they land at as it is written, so the whole append is one view per row with no byte copy and no intermediate array. view_at is only called for valid rows; null rows get an empty view.

When the builder is configured to compact buffers, utilization is measured from the views the gather actually references — duplicate indices count once — and each buffer is adopted, sliced, or rewritten accordingly, so callers never need a canonicalize-and-compact fallback.

Panics

Panics if view_at returns an index out of bounds of views, or if a gathered view references a buffer index outside buffers.

pub fn append_views_scattered( &mut self, buffers: impl IntoIterator<Item = ByteBuffer>, len: usize, fill: BinaryView, patches: impl Iterator<Item = (usize, BinaryView)>, validity: &Mask, )

Appends len rows that are fill everywhere except at the given patch rows.

buffers — the data buffers fill and the patch views reference, in the numbering they use — are adopted through the builder’s buffer storage and the views are rebased onto the indices they land at. patches yields (row, view) pairs with rows below len; the fill rows cost one bulk view fill and each patch one view write, with no byte copy. Validity is appended exactly as given — invalid rows keep whichever view they got.

This append deliberately adopts the supplied buffers as-is, even when the builder is configured for compaction. Callers should use it only when retaining those buffers is acceptable.

Panics

Panics if validity is not len long, a patch row is out of bounds, or a view references a buffer index outside buffers.

pub fn append_buffer_with_lengths<P: NativePType + AsPrimitive<usize>>( &mut self, bytes: ByteBuffer, lengths: &[P], validity: &Mask, )

Appends values laid end-to-end in bytes, one per entry of lengths.

The builder adopts bytes as a data buffer without copying it (splitting it only past the u32 view-offset limit) and builds the views directly into its own storage, so the whole append costs one view per row. Every length is consumed, including those for null rows, so the lengths must describe bytes exactly; bytes belonging to null rows are not retained when compaction rewrites the buffer.

When the builder is configured to compact buffers, the utilization is measured from the lengths alone — only values too long to inline reference the buffer — and a heap below the threshold is rewritten to just those values instead of adopted, so callers never need a canonicalize-and-compact fallback.

Panics

Panics if lengths and validity disagree in length, if the lengths do not describe bytes exactly, or if this builder deduplicates buffers and already holds bytes.

pub fn append_buffer_with_offsets<P: NativePType + AsPrimitive<usize>>( &mut self, bytes: ByteBuffer, offsets: &[P], validity: &Mask, )

append_buffer_with_lengths for values described by an offsets buffer instead of lengths.

offsets are absolute positions into bytes — the layout a VarBinArray stores — so there is one more offset than there are values, and only the offsets[0]..offsets[last] range of bytes is adopted, again without copying.

Panics

Panics if offsets does not hold exactly one more entry than validity, or if the offsets are not monotonically non-decreasing positions within bytes.

pub fn finish_into_varbinview(&mut self) -> VarBinViewArray

Finishes the builder directly into a VarBinViewArray.

Trait Implementations

impl ArrayBuilder for VarBinViewBuilder

fn as_any(&self) -> &dyn Any

fn as_any_mut(&mut self) -> &mut dyn Any

fn dtype(&self) -> &DType

fn len(&self) -> usize

fn append_zeros(&mut self, n: usize)

Appends n “zero” values to the array.

unsafe fn append_nulls_unchecked(&mut self, n: usize)

The inner part of append_nulls.

fn append_scalar(&mut self, scalar: &Scalar) -> VortexResult<()>

A generic function to append a scalar to the builder.

fn reserve_exact(&mut self, additional: usize)

Allocate space for extra additional items

unsafe fn set_validity_unchecked(&mut self, validity: Mask)

override validity with the one provided, without checking lengths

fn finish(&mut self) -> ArrayRef

Constructs an Array from the builder components.

fn finish_into_canonical(&mut self, _ctx: &mut ExecutionCtx) -> Canonical

Constructs a canonical array directly from the builder.

fn is_empty(&self) -> bool

fn append_zero(&mut self)

Append a “zero” value to the array.

fn append_null(&mut self)

Append a “null” value to the array.

fn append_nulls(&mut self, n: usize)

Appends n “null” values to the array.

fn append_default(&mut self)

Appends a default value to the array.

fn append_defaults(&mut self, n: usize)

Appends n default values to the array.

fn set_validity(&mut self, validity: Mask)

Override builders validity with the one provided.