Struct VectorWriter 

pub struct VectorWriter { /* private fields */ }

A typed writer for a DuckDB output vector in a finalize callback.

Example

use quack_rs::vector::VectorWriter;
use libduckdb_sys::duckdb_vector;

// Inside finalize:
// let mut writer = unsafe { VectorWriter::new(result_vector) };
// for row in 0..count {
//     if let Some(val) = compute_result(row) {
//         unsafe { writer.write_i64(row, val) };
//     } else {
//         unsafe { writer.set_null(row) };
//     }
// }

Implementations

impl VectorWriter

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

Creates a new VectorWriter for the given result vector.

Safety

vector must be a valid DuckDB output vector obtained in a finalize callback. The vector must not be destroyed while this writer is live.

pub unsafe fn from_vector(vector: duckdb_vector) -> Self

Creates a VectorWriter directly from a raw duckdb_vector handle.

Use this when you need to write into a child vector (e.g., a STRUCT field or LIST element vector) obtained from StructVector::get_child or ListVector::get_child.

Safety

vector must be a valid, writable duckdb_vector. The vector must not be destroyed while this writer is live.

pub const unsafe fn write_i8(&mut self, idx: usize, value: i8)

Writes an i8 (TINYINT) value at row idx.

Safety

• idx must be within the vector’s capacity.
• The vector must have TINYINT type.

pub const unsafe fn write_i16(&mut self, idx: usize, value: i16)

Writes an i16 (SMALLINT) value at row idx.

Safety

See write_i8.

pub const unsafe fn write_i32(&mut self, idx: usize, value: i32)

Writes an i32 (INTEGER) value at row idx.

Safety

See write_i8.

pub const unsafe fn write_i64(&mut self, idx: usize, value: i64)

Writes an i64 (BIGINT / TIMESTAMP) value at row idx.

Safety

See write_i8.

pub const unsafe fn write_u8(&mut self, idx: usize, value: u8)

Writes a u8 (UTINYINT) value at row idx.

Safety

See write_i8.

pub const unsafe fn write_u32(&mut self, idx: usize, value: u32)

Writes a u32 (UINTEGER) value at row idx.

Safety

See write_i8.

pub const unsafe fn write_u64(&mut self, idx: usize, value: u64)

Writes a u64 (UBIGINT) value at row idx.

Safety

See write_i8.

pub const unsafe fn write_f32(&mut self, idx: usize, value: f32)

Writes an f32 (FLOAT) value at row idx.

Safety

See write_i8.

pub const unsafe fn write_f64(&mut self, idx: usize, value: f64)

Writes an f64 (DOUBLE) value at row idx.

Safety

See write_i8.

pub unsafe fn write_bool(&mut self, idx: usize, value: bool)

Writes a bool (BOOLEAN) value at row idx.

Booleans are stored as a single byte: 1 for true, 0 for false.

Safety

• idx must be within the vector’s capacity.
• The vector must have BOOLEAN type.

pub const unsafe fn write_i128(&mut self, idx: usize, value: i128)

Writes an i128 (HUGEINT) value at row idx.

DuckDB stores HUGEINT as { lower: u64, upper: i64 } in little-endian layout, totaling 16 bytes per value.

Safety

• idx must be within the vector’s capacity.
• The vector must have HUGEINT type.

pub const unsafe fn write_u16(&mut self, idx: usize, value: u16)

Writes a u16 (USMALLINT) value at row idx.

Safety

See write_i8.

pub unsafe fn write_varchar(&mut self, idx: usize, value: &str)

Writes a VARCHAR string value at row idx.

This uses duckdb_vector_assign_string_element_len which handles both the inline (≤12 bytes) and pointer (>12 bytes) storage formats automatically. DuckDB manages the memory for the string data.

Note on very long strings

If value.len() exceeds idx_t::MAX (2^64 − 1 on 64-bit platforms), the length is silently clamped to idx_t::MAX. In practice, this limit is unreachable on any current hardware (≈18 exabytes), so no explicit error path is provided.

Safety

• idx must be within the vector’s capacity.
• The vector must have VARCHAR type.

pub const unsafe fn write_date(&mut self, idx: usize, days_since_epoch: i32)

Writes a DATE value at row idx as days since the Unix epoch.

DuckDB stores DATE as a 4-byte i32. This is a semantic alias for write_i32.

Safety

• idx must be within the vector’s capacity.
• The vector must have DATE type.

pub const unsafe fn write_timestamp( &mut self, idx: usize, micros_since_epoch: i64, )

Writes a TIMESTAMP value at row idx as microseconds since the Unix epoch.

DuckDB stores TIMESTAMP as an 8-byte i64. This is a semantic alias for write_i64.

Safety

• idx must be within the vector’s capacity.
• The vector must have TIMESTAMP type.

pub const unsafe fn write_time( &mut self, idx: usize, micros_since_midnight: i64, )

Writes a TIME value at row idx as microseconds since midnight.

DuckDB stores TIME as an 8-byte i64. This is a semantic alias for write_i64.

Safety

• idx must be within the vector’s capacity.
• The vector must have TIME type.

pub const unsafe fn write_interval(&mut self, idx: usize, value: DuckInterval)

Writes an INTERVAL value at row idx.

DuckDB stores INTERVAL as { months: i32, days: i32, micros: i64 } in a 16-byte layout. This method writes all three components at the correct offsets.

Safety

• idx must be within the vector’s capacity.
• The vector must have INTERVAL type.

pub unsafe fn write_blob(&mut self, idx: usize, value: &[u8])

Writes a BLOB (binary) value at row idx.

This uses the same underlying storage as VARCHAR — DuckDB stores BLOBs using duckdb_vector_assign_string_element_len, which copies the data.

Safety

• idx must be within the vector’s capacity.
• The vector must have BLOB type.

pub const unsafe fn write_uuid(&mut self, idx: usize, bits: u128)

Writes a UUID value at row idx.

Writes bits — the UUID’s textual 128 bits, as every Rust Uuid type holds them — at row idx.

A UUID column is physically a HUGEINT, but DuckDB stores it with the top bit flipped so that signed integer ordering matches UUID string ordering. This applies that flip, so the value you pass is the value the column renders. Use write_i128 to write the raw storage instead, and uuid_to_storage to convert between the two.

Safety

• idx must be within the vector’s capacity.
• The vector must have UUID type.

pub unsafe fn write_str(&mut self, idx: usize, value: &str)

Writes a VARCHAR string value at row idx.

This is an alias for write_varchar provided for discoverability — extension authors often look for write_str first.

Safety

• idx must be within the vector’s capacity.
• The vector must have VARCHAR type.

pub const unsafe fn write_u128(&mut self, idx: usize, value: u128)

Writes a u128 (UHUGEINT) value at row idx.

DuckDB stores UHUGEINT as { lower: u64, upper: u64 } in little-endian layout, totalling 16 bytes per value.

Safety

• idx must be within the vector’s capacity.
• The vector must have UHUGEINT type.

pub const unsafe fn write_timestamp_tz( &mut self, idx: usize, micros_since_epoch: i64, )

Writes a TIMESTAMP WITH TIME ZONE value at row idx, as microseconds since the Unix epoch in UTC.

TIMESTAMPTZ shares TIMESTAMP’s 8-byte i64 storage; only the logical type differs.

Safety

• idx must be within the vector’s capacity.
• The vector must have TIMESTAMPTZ type.

pub const unsafe fn write_timestamp_s( &mut self, idx: usize, seconds_since_epoch: i64, )

Writes a TIMESTAMP_S value at row idx, as seconds since the epoch.

Safety

• idx must be within the vector’s capacity.
• The vector must have TIMESTAMP_S type.

pub const unsafe fn write_timestamp_ms( &mut self, idx: usize, millis_since_epoch: i64, )

Writes a TIMESTAMP_MS value at row idx, as milliseconds since the epoch.

Safety

• idx must be within the vector’s capacity.
• The vector must have TIMESTAMP_MS type.

pub const unsafe fn write_timestamp_ns( &mut self, idx: usize, nanos_since_epoch: i64, )

Writes a TIMESTAMP_NS value at row idx, as nanoseconds since the epoch.

Safety

• idx must be within the vector’s capacity.
• The vector must have TIMESTAMP_NS type.

pub const unsafe fn write_time_tz(&mut self, idx: usize, bits: u64)

Writes a TIME WITH TIME ZONE value at row idx.

bits is DuckDB’s packed representation; build one with datetime::time_tz_bits rather than assembling it by hand.

Safety

• idx must be within the vector’s capacity.
• The vector must have TIMETZ type.

pub const unsafe fn write_decimal( &mut self, idx: usize, width: u8, unscaled: i128, )

Writes a DECIMAL value at row idx from its unscaled representation.

DuckDB stores a DECIMAL in the narrowest integer that fits its declared width — i16 up to 4 digits, i32 up to 9, i64 up to 18, and i128 beyond — so the width must match the column’s type. Get it from LogicalType::decimal_width.

Safety

• idx must be within the vector’s capacity.
• The vector must have DECIMAL type with exactly this width.

pub unsafe fn set_null(&mut self, idx: usize)

Marks row idx as NULL in the output vector.

Pitfall L4: ensure_validity_writable

This method calls duckdb_vector_ensure_validity_writable before duckdb_vector_get_validity, which is required before writing any NULL flags. Forgetting this call returns an uninitialized pointer.

Safety

• idx must be within the vector’s capacity.

pub unsafe fn set_null_range(&mut self, range: Range<usize>)

Marks every row in range as NULL.

Equivalent to calling set_null for each index, but resolves the validity bitmap once.

Safety

Every index in range must be within the vector’s capacity.

pub unsafe fn set_valid(&mut self, idx: usize)

Marks row idx as valid (non-NULL) in the output vector.

Use this to undo a previous set_null call for a row, or to explicitly mark a row as valid after writing its value.

Like set_null, this calls ensure_validity_writable before modifying the validity bitmap.

Safety

• idx must be within the vector’s capacity.

pub const fn as_raw(&self) -> duckdb_vector

Returns the underlying raw vector handle.

Trait Implementations

impl Debug for VectorWriter

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

Formats the value using the given formatter.