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
impl ListBuilder
Sourcepub const unsafe fn new(vector: duckdb_vector) -> Self
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.
Sourcepub const fn with_element_limit(self, limit: usize) -> Self
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.
Sourcepub const fn element_count(&self) -> usize
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).
Sourcepub const fn overflowed(&self) -> bool
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.
Sourcepub unsafe fn push_row<F>(&mut self, row_idx: usize, len: usize, write: F)
pub unsafe fn push_row<F>(&mut self, row_idx: usize, len: usize, write: F)
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_idxmust 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.
Sourcepub unsafe fn push_map_row<F>(&mut self, row_idx: usize, len: usize, write: F)
pub unsafe fn push_map_row<F>(&mut self, row_idx: usize, len: usize, write: F)
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.vectormust be aMAPvector.row_idxmust be within the parent vector’s capacity.- The closure must only write child indices in
base..base + len.
Sourcepub unsafe fn finish(self)
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.