pub struct StructWriter { /* private fields */ }Expand description
A batched writer for STRUCT output vectors.
Pre-creates a VectorWriter for every field at construction, allowing
direct typed writes without repeated duckdb_struct_vector_get_child calls.
Implementations§
Source§impl StructWriter
impl StructWriter
Sourcepub unsafe fn new(vector: duckdb_vector, field_count: usize) -> Self
pub unsafe fn new(vector: duckdb_vector, field_count: usize) -> Self
Creates a new StructWriter for a STRUCT vector with field_count fields.
This pre-creates a VectorWriter for each field index 0..field_count.
§Safety
vectormust be a valid, writableDuckDBSTRUCT vector.field_countmust match the number of fields in the STRUCT type.- The vector must remain valid for the lifetime of this writer.
- If
vectorlies inside the child of aLISTorMAPvector — is that child, or a STRUCT field or ARRAY element vector below it with no otherLISTorMAPin between — the writer must not be used after thatLISTorMAPis grown with areserve: growing reallocates the fields’ data and validity buffers, and the writer caches pointers to them.
Sourcepub fn field_count(&self) -> usize
pub fn field_count(&self) -> usize
Returns the number of fields in this struct writer.
Sourcepub fn child_vector(&self, field_idx: usize) -> duckdb_vector
pub fn child_vector(&self, field_idx: usize) -> duckdb_vector
Returns the raw duckdb_vector handle for the given field.
Use this when a struct field has a complex type (LIST, MAP, ARRAY) that
requires operations beyond simple scalar writes — for example, calling
ListVector::set_entry or
ListVector::reserve.
§Example
use quack_rs::vector::{StructWriter, VectorWriter, complex::ListVector};
use libduckdb_sys::duckdb_vector;
// Given a STRUCT output vector where field 1 is LIST<VARCHAR>:
// let mut sw = unsafe { StructWriter::new(struct_vec, 3) };
// sw.write_varchar(0, 0, "name"); // scalar field
// let list_vec = sw.child_vector(1); // LIST field
// unsafe { ListVector::reserve(list_vec, 10) }; // complex ops
// unsafe { ListVector::set_entry(list_vec, 0, 0, 3) };
// let mut elem = unsafe { ListVector::child_writer(list_vec) };
// unsafe { elem.write_varchar(0, "a") };
// unsafe { ListVector::set_size(list_vec, 3) };§Panics
Panics if field_idx >= field_count.
Sourcepub fn field_mut(&mut self, field_idx: usize) -> &mut VectorWriter
pub fn field_mut(&mut self, field_idx: usize) -> &mut VectorWriter
Returns a mutable reference to the VectorWriter for the given field.
Do not replace the writer through this reference (by assignment or
std::mem::swap): the write_* methods write to whatever writer is at
the field’s index, and their Safety sections require that it is still
the field’s own.
§Panics
Panics if field_idx >= field_count.
Sourcepub fn child_list_vector(&self, field_idx: usize) -> duckdb_vector
pub fn child_list_vector(&self, field_idx: usize) -> duckdb_vector
Returns the raw duckdb_vector handle for a LIST-typed field.
This is a semantic alias for child_vector that
makes the intent clear when a struct field has LIST type. Use the
returned handle with ListVector
methods (reserve, set_entry, set_size, child_writer, etc.).
§Example
use quack_rs::vector::{StructWriter, VectorWriter, complex::ListVector};
use libduckdb_sys::duckdb_vector;
// Given a STRUCT output vector where field 2 is LIST<VARCHAR>:
// let mut sw = unsafe { StructWriter::new(struct_vec, 4) };
// let list_vec = sw.child_list_vector(2);
// unsafe { ListVector::reserve(list_vec, 10) };
// unsafe { ListVector::set_entry(list_vec, 0, 0, 3) };
// let mut elem_writer = unsafe { ListVector::child_writer(list_vec) };
// unsafe {
// elem_writer.write_varchar(0, "a");
// elem_writer.write_varchar(1, "b");
// elem_writer.write_varchar(2, "c");
// }
// unsafe { ListVector::set_size(list_vec, 3) };§Panics
Panics if field_idx >= field_count.
Sourcepub unsafe fn write_bool(&mut self, row: usize, field_idx: usize, value: bool)
pub unsafe fn write_bool(&mut self, row: usize, field_idx: usize, value: bool)
Writes a bool value to field field_idx at row row.
§Safety
rowmust be within the vector’s capacity.- The field at
field_idxmust haveBOOLEANtype. - No field writer has been replaced through
field_mut(by assignment orstd::mem::swap): the write goes to whatever writer is atfield_idx, and the other conditions are about fieldfield_idx.
§Panics
Panics if field_idx >= field_count.
Sourcepub unsafe fn write_varchar(
&mut self,
row: usize,
field_idx: usize,
value: &str,
)
pub unsafe fn write_varchar( &mut self, row: usize, field_idx: usize, value: &str, )
Writes a VARCHAR string value to field field_idx at row row.
§Safety
rowmust be within the vector’s capacity.- The field at
field_idxmust haveVARCHARtype. - No field writer has been replaced through
field_mut(by assignment orstd::mem::swap): the write goes to whatever writer is atfield_idx, and the other conditions are about fieldfield_idx.
§Panics
Panics if field_idx >= field_count, or if value is longer than
MAX_STRING_LEN (see
VectorWriter::write_varchar).
Sourcepub unsafe fn write_i8(&mut self, row: usize, field_idx: usize, value: i8)
pub unsafe fn write_i8(&mut self, row: usize, field_idx: usize, value: i8)
Writes an i8 (TINYINT) value to field field_idx at row row.
§Safety
rowmust be within the vector’s capacity.- The field at
field_idxmust haveTINYINTtype. - No field writer has been replaced through
field_mut(by assignment orstd::mem::swap): the write goes to whatever writer is atfield_idx, and the other conditions are about fieldfield_idx.
§Panics
Panics if field_idx >= field_count.
Sourcepub unsafe fn write_i128(&mut self, row: usize, field_idx: usize, value: i128)
pub unsafe fn write_i128(&mut self, row: usize, field_idx: usize, value: i128)
Sourcepub unsafe fn write_interval(
&mut self,
row: usize,
field_idx: usize,
value: DuckInterval,
)
pub unsafe fn write_interval( &mut self, row: usize, field_idx: usize, value: DuckInterval, )
Sourcepub unsafe fn write_blob(&mut self, row: usize, field_idx: usize, value: &[u8])
pub unsafe fn write_blob(&mut self, row: usize, field_idx: usize, value: &[u8])
Writes a BLOB (binary) value to field field_idx at row row.
§Safety
See write_i8.
§Panics
Panics if field_idx >= field_count, or if value is longer than
MAX_STRING_LEN.
Sourcepub unsafe fn write_uuid(&mut self, row: usize, field_idx: usize, value: u128)
pub unsafe fn write_uuid(&mut self, row: usize, field_idx: usize, value: u128)
Writes a UUID’s textual 128 bits to field field_idx at row row.
See VectorWriter::write_uuid
for why this is not the raw HUGEINT storage.
§Safety
See write_i8.
Sourcepub unsafe fn write_str(&mut self, row: usize, field_idx: usize, value: &str)
pub unsafe fn write_str(&mut self, row: usize, field_idx: usize, value: &str)
Writes a VARCHAR string value to field field_idx at row row.
Alias for write_varchar.
§Safety
See write_varchar.
Sourcepub unsafe fn write_date(
&mut self,
row: usize,
field_idx: usize,
days_since_epoch: i32,
)
pub unsafe fn write_date( &mut self, row: usize, field_idx: usize, days_since_epoch: i32, )
Sourcepub unsafe fn write_timestamp(
&mut self,
row: usize,
field_idx: usize,
micros_since_epoch: i64,
)
pub unsafe fn write_timestamp( &mut self, row: usize, field_idx: usize, micros_since_epoch: i64, )
Sourcepub unsafe fn write_time(
&mut self,
row: usize,
field_idx: usize,
micros_since_midnight: i64,
)
pub unsafe fn write_time( &mut self, row: usize, field_idx: usize, micros_since_midnight: i64, )
Writes a TIME value (microseconds since midnight) to field field_idx at row row.
Semantic alias for write_i64.
§Safety
See write_i8. Also, micros_since_midnight must be
in 0..=86_400_000_000: see
VectorWriter::write_time,
whose out-of-range values crash DuckDB when it renders them.
Sourcepub unsafe fn set_row_null(&mut self, row: usize)
pub unsafe fn set_row_null(&mut self, row: usize)
Marks the whole struct at row row as NULL — the struct itself and
every field, recursively.
This is what DuckDB does internally for a NULL struct row. Marking only
the fields NULL leaves the row a valid struct of NULLs ({'a': NULL}),
not a NULL; marking only the parent (a bare
duckdb_validity_set_row_invalid) leaves the fields valid, so
struct_extract on the NULL row returns their stale values.
§Safety
rowmust be within the vector’s capacity.
Sourcepub unsafe fn set_null(&mut self, row: usize, field_idx: usize)
pub unsafe fn set_null(&mut self, row: usize, field_idx: usize)
Marks field field_idx at row row as NULL.
To make the whole struct row NULL use
set_row_null instead.
§Safety
rowmust be within the vector’s capacity.- No field writer has been replaced through
field_mut(by assignment orstd::mem::swap): the write goes to whatever writer is atfield_idx, and the other conditions are about fieldfield_idx.
§Panics
Panics if field_idx >= field_count.
Sourcepub unsafe fn set_valid(&mut self, row: usize, field_idx: usize)
pub unsafe fn set_valid(&mut self, row: usize, field_idx: usize)
Marks field field_idx at row row as valid (non-NULL).
Use this to undo a previous set_null call.
§Safety
rowmust be within the vector’s capacity.- No field writer has been replaced through
field_mut(by assignment orstd::mem::swap): the write goes to whatever writer is atfield_idx, and the other conditions are about fieldfield_idx.
§Panics
Panics if field_idx >= field_count.