Skip to main content

ListBuilder

Struct ListBuilder 

Source
pub struct ListBuilder { /* private fields */ }
Expand description

Incremental builder for a LIST (or MAP) output vector.

See the module docs for why the manual sequence is easy to get wrong.

Implementations§

Source§

impl ListBuilder

Source

pub const unsafe fn new(vector: duckdb_vector) -> Self

Starts building into vector.

Rows are appended after any elements the vector’s child already holds, so several builders — or several calls of a callback — can fill one vector in turn. DuckDB relies on this: it can call an aggregate’s finalize many times on the same result vector with an increasing offset, one row per call (agg(x ORDER BY y) finalizes through SortedAggregateFunction that way), and a builder that started at child offset 0 each time would overwrite the earlier rows’ elements. A fresh output vector has an empty child, so for a scalar function this makes no difference. The element limit counts the elements already there.

§Safety

vector must be a valid, writable LIST or MAP output vector.

Source

pub const fn with_element_limit(self, limit: usize) -> Self

Lowers the number of child elements this builder will reserve, in total across all rows. Values above MAX_LIST_CHILD_CAPACITY are clamped to it.

§Why an extension needs this

max_child_capacity is DuckDB’s own ceiling for the child’s type (2^37 bytes, rounded to a power-of-two element count), which the builder applies by itself — far more memory than most machines have. A request below that ceiling that the allocator cannot satisfy makes DuckDB throw from duckdb_list_vector_reserve, which has no try/catch (DuckDB 1.5.5, src/main/capi/data_chunk-c.cpp), so the exception unwinds into Rust and the process aborts. Nothing in this crate can catch it. When row lengths come from untrusted input, set a limit that fits in memory; a row that would exceed it is written as NULL and overflowed reports it.

Source

pub const fn element_count(&self) -> usize

Elements in the child vector so far: those this builder wrote, plus any the vector already held when the builder started (see new).

Source

pub const fn overflowed(&self) -> bool

Returns true if a row would have taken the child vector past the element limit (max_child_capacity, or the one set with with_element_limit).

From that row on, the builder writes nothing into the child: that row and every later push_row / push_map_row row is set to NULL, with an empty list entry. Rows written before it stay valid. Check this before finish if the row lengths come from untrusted input, and report an error if a NULL is not an acceptable answer.

Source

pub unsafe fn push_row<F>(&mut self, row_idx: usize, len: usize, write: F)
where F: FnOnce(&mut VectorWriter, usize),

Appends len elements for parent row row_idx.

The closure receives a VectorWriter for the child vector — obtained after the last reserve, so it is never stale, and the same writer for every row between two reserves — and base, the index the row’s first element occupies. Write indices base..base + len.

If the row would exceed the element limit — or an earlier row already did — the closure is not called and the row is written as NULL; see overflowed.

§Safety
  • row_idx must be within the parent vector’s capacity.
  • The closure must only write child indices in base..base + len, using accessors matching the child’s type.
Source

pub unsafe fn push_map_row<F>(&mut self, row_idx: usize, len: usize, write: F)
where F: FnOnce(&mut VectorWriter, &mut VectorWriter, usize),

Appends len key/value pairs for parent row row_idx of a MAP.

The closure receives a writer for the key child, a writer for the value child, and the base index. Write indices base..base + len in both.

Past the element limit the row is written as NULL, exactly as for push_row.

§Safety
  • self.vector must be a MAP vector.
  • row_idx must be within the parent vector’s capacity.
  • The closure must only write child indices in base..base + len.
Source

pub unsafe fn finish(self)

Declares how many child elements are valid, completing the vector.

Forgetting this leaves DuckDB reading a child size of zero, so the column comes back as empty lists with no error.

§Safety

Every element promised by a push_row / push_map_row call must actually have been written.

Trait Implementations§

Source§

impl Debug for ListBuilder

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.