Skip to main content

quack_rs/vector/
struct_writer.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! Batched, typed writer for STRUCT output vectors.
7//!
8//! [`StructWriter`] pre-creates [`VectorWriter`]s for every field at construction,
9//! then exposes typed `write_*` methods that take `(row, field_idx, value)`.
10//! This eliminates the repetitive `duckdb_struct_vector_get_child` + manual
11//! `VectorWriter` creation that extension authors currently need for every field.
12//!
13//! # Example
14//!
15//! ```rust,no_run
16//! use quack_rs::vector::StructWriter;
17//! use libduckdb_sys::duckdb_vector;
18//!
19//! // Inside a scan callback, given a STRUCT output vector with 5 fields:
20//! // let mut sw = unsafe { StructWriter::new(struct_vec, 5) };
21//! // unsafe {
22//! //     sw.write_bool(0, 0, result.success);
23//! //     sw.write_varchar(0, 1, &result.data);
24//! //     sw.write_i64(0, 2, result.lease);
25//! //     sw.write_bool(0, 3, result.renewable);
26//! //     sw.write_varchar(0, 4, &result.message);
27//! // }
28//! ```
29//!
30//! It fetches every field's child vector once, up front, so a loop writing
31//! `n` rows of `k` fields makes `k` `duckdb_struct_vector_get_child` calls
32//! instead of one per write.
33
34use libduckdb_sys::duckdb_vector;
35
36use crate::interval::DuckInterval;
37use crate::vector::complex::StructVector;
38use crate::vector::VectorWriter;
39
40/// A batched writer for STRUCT output vectors.
41///
42/// Pre-creates a [`VectorWriter`] for every field at construction, allowing
43/// direct typed writes without repeated `duckdb_struct_vector_get_child` calls.
44#[derive(Debug)]
45pub struct StructWriter {
46    /// The STRUCT vector itself, for row-level NULLs.
47    parent: VectorWriter,
48    fields: Vec<VectorWriter>,
49}
50
51impl StructWriter {
52    /// Creates a new `StructWriter` for a STRUCT vector with `field_count` fields.
53    ///
54    /// This pre-creates a [`VectorWriter`] for each field index `0..field_count`.
55    ///
56    /// # Safety
57    ///
58    /// - `vector` must be a valid, writable `DuckDB` STRUCT vector.
59    /// - `field_count` must match the number of fields in the STRUCT type.
60    /// - The vector must remain valid for the lifetime of this writer.
61    /// - If `vector` lies inside the child of a `LIST` or `MAP` vector — is
62    ///   that child, or a STRUCT field or ARRAY element vector below it with no
63    ///   other `LIST` or `MAP` in between — the writer must not be used after
64    ///   that `LIST` or `MAP` is grown with a `reserve`: growing reallocates
65    ///   the fields' data and validity buffers, and the writer caches pointers
66    ///   to them.
67    pub unsafe fn new(vector: duckdb_vector, field_count: usize) -> Self {
68        let mut fields = Vec::with_capacity(field_count);
69        for idx in 0..field_count {
70            // SAFETY: caller guarantees vector is valid STRUCT with field_count fields.
71            fields.push(unsafe { StructVector::field_writer(vector, idx) });
72        }
73        // SAFETY: caller guarantees vector is a valid, writable STRUCT vector.
74        let parent = unsafe { VectorWriter::from_vector(vector) };
75        Self { parent, fields }
76    }
77
78    /// Returns the number of fields in this struct writer.
79    #[cfg_attr(test, mutants::skip)]
80    #[must_use]
81    #[inline]
82    pub fn field_count(&self) -> usize {
83        self.fields.len()
84    }
85
86    /// Returns the raw `duckdb_vector` handle for the given field.
87    ///
88    /// Use this when a struct field has a complex type (LIST, MAP, ARRAY) that
89    /// requires operations beyond simple scalar writes — for example, calling
90    /// [`ListVector::set_entry`][crate::vector::complex::ListVector::set_entry] or
91    /// [`ListVector::reserve`][crate::vector::complex::ListVector::reserve].
92    ///
93    /// # Example
94    ///
95    /// ```rust,no_run
96    /// use quack_rs::vector::{StructWriter, VectorWriter, complex::ListVector};
97    /// use libduckdb_sys::duckdb_vector;
98    ///
99    /// // Given a STRUCT output vector where field 1 is LIST<VARCHAR>:
100    /// // let mut sw = unsafe { StructWriter::new(struct_vec, 3) };
101    /// // sw.write_varchar(0, 0, "name");               // scalar field
102    /// // let list_vec = sw.child_vector(1);             // LIST field
103    /// // unsafe { ListVector::reserve(list_vec, 10) };  // complex ops
104    /// // unsafe { ListVector::set_entry(list_vec, 0, 0, 3) };
105    /// // let mut elem = unsafe { ListVector::child_writer(list_vec) };
106    /// // unsafe { elem.write_varchar(0, "a") };
107    /// // unsafe { ListVector::set_size(list_vec, 3) };
108    /// ```
109    ///
110    /// # Panics
111    ///
112    /// Panics if `field_idx >= field_count`.
113    #[must_use]
114    #[inline]
115    pub fn child_vector(&self, field_idx: usize) -> duckdb_vector {
116        self.fields[field_idx].as_raw()
117    }
118
119    /// Returns a mutable reference to the [`VectorWriter`] for the given field.
120    ///
121    /// Do not replace the writer through this reference (by assignment or
122    /// `std::mem::swap`): the `write_*` methods write to whatever writer is at
123    /// the field's index, and their Safety sections require that it is still
124    /// the field's own.
125    ///
126    /// # Panics
127    ///
128    /// Panics if `field_idx >= field_count`.
129    #[must_use]
130    #[inline]
131    pub fn field_mut(&mut self, field_idx: usize) -> &mut VectorWriter {
132        &mut self.fields[field_idx]
133    }
134
135    /// Returns the raw `duckdb_vector` handle for a LIST-typed field.
136    ///
137    /// This is a semantic alias for [`child_vector`][Self::child_vector] that
138    /// makes the intent clear when a struct field has `LIST` type. Use the
139    /// returned handle with [`ListVector`][crate::vector::complex::ListVector]
140    /// methods (`reserve`, `set_entry`, `set_size`, `child_writer`, etc.).
141    ///
142    /// # Example
143    ///
144    /// ```rust,no_run
145    /// use quack_rs::vector::{StructWriter, VectorWriter, complex::ListVector};
146    /// use libduckdb_sys::duckdb_vector;
147    ///
148    /// // Given a STRUCT output vector where field 2 is LIST<VARCHAR>:
149    /// // let mut sw = unsafe { StructWriter::new(struct_vec, 4) };
150    /// // let list_vec = sw.child_list_vector(2);
151    /// // unsafe { ListVector::reserve(list_vec, 10) };
152    /// // unsafe { ListVector::set_entry(list_vec, 0, 0, 3) };
153    /// // let mut elem_writer = unsafe { ListVector::child_writer(list_vec) };
154    /// // unsafe {
155    /// //     elem_writer.write_varchar(0, "a");
156    /// //     elem_writer.write_varchar(1, "b");
157    /// //     elem_writer.write_varchar(2, "c");
158    /// // }
159    /// // unsafe { ListVector::set_size(list_vec, 3) };
160    /// ```
161    ///
162    /// # Panics
163    ///
164    /// Panics if `field_idx >= field_count`.
165    #[must_use]
166    #[inline]
167    pub fn child_list_vector(&self, field_idx: usize) -> duckdb_vector {
168        self.child_vector(field_idx)
169    }
170
171    /// Writes a `bool` value to field `field_idx` at row `row`.
172    ///
173    /// # Safety
174    ///
175    /// - `row` must be within the vector's capacity.
176    /// - The field at `field_idx` must have `BOOLEAN` type.
177    /// - No field writer has been replaced through [`field_mut`][Self::field_mut]
178    ///   (by assignment or `std::mem::swap`): the write goes to whatever writer
179    ///   is at `field_idx`, and the other conditions are about field `field_idx`.
180    ///
181    /// # Panics
182    ///
183    /// Panics if `field_idx >= field_count`.
184    #[inline]
185    pub unsafe fn write_bool(&mut self, row: usize, field_idx: usize, value: bool) {
186        // SAFETY: caller guarantees row is in bounds and field type is BOOLEAN.
187        unsafe { self.fields[field_idx].write_bool(row, value) };
188    }
189
190    /// Writes a VARCHAR string value to field `field_idx` at row `row`.
191    ///
192    /// # Safety
193    ///
194    /// - `row` must be within the vector's capacity.
195    /// - The field at `field_idx` must have `VARCHAR` type.
196    /// - No field writer has been replaced through [`field_mut`][Self::field_mut]
197    ///   (by assignment or `std::mem::swap`): the write goes to whatever writer
198    ///   is at `field_idx`, and the other conditions are about field `field_idx`.
199    ///
200    /// # Panics
201    ///
202    /// Panics if `field_idx >= field_count`, or if `value` is longer than
203    /// [`MAX_STRING_LEN`][crate::vector::string::MAX_STRING_LEN] (see
204    /// [`VectorWriter::write_varchar`][crate::vector::VectorWriter::write_varchar]).
205    #[inline]
206    pub unsafe fn write_varchar(&mut self, row: usize, field_idx: usize, value: &str) {
207        // SAFETY: caller guarantees row is in bounds and field type is VARCHAR.
208        unsafe { self.fields[field_idx].write_varchar(row, value) };
209    }
210
211    /// Writes an `i8` (TINYINT) value to field `field_idx` at row `row`.
212    ///
213    /// # Safety
214    ///
215    /// - `row` must be within the vector's capacity.
216    /// - The field at `field_idx` must have `TINYINT` type.
217    /// - No field writer has been replaced through [`field_mut`][Self::field_mut]
218    ///   (by assignment or `std::mem::swap`): the write goes to whatever writer
219    ///   is at `field_idx`, and the other conditions are about field `field_idx`.
220    ///
221    /// # Panics
222    ///
223    /// Panics if `field_idx >= field_count`.
224    #[inline]
225    pub unsafe fn write_i8(&mut self, row: usize, field_idx: usize, value: i8) {
226        // SAFETY: `VectorWriter::write_i8` needs `row` within the vector's capacity
227        // and a TINYINT vector. `self.fields[field_idx]` (bounds-checked) wraps STRUCT
228        // child `field_idx` (`new` put it there; the `# Safety` contract says no
229        // writer was replaced through `field_mut`), which DuckDB allocates with the parent's capacity
230        // (`VectorStructBuffer` constructor, vector_buffer.cpp) and which `new`'s
231        // contract keeps valid; the `# Safety` contract (`write_i8`'s, for the field's
232        // own type) gives `row` within that capacity and a TINYINT field.
233        unsafe { self.fields[field_idx].write_i8(row, value) };
234    }
235
236    /// Writes an `i16` (SMALLINT) value to field `field_idx` at row `row`.
237    ///
238    /// # Safety
239    ///
240    /// See [`write_i8`][Self::write_i8].
241    #[inline]
242    pub unsafe fn write_i16(&mut self, row: usize, field_idx: usize, value: i16) {
243        // SAFETY: `VectorWriter::write_i16` needs `row` within the vector's capacity
244        // and a SMALLINT vector. `self.fields[field_idx]` (bounds-checked) wraps STRUCT
245        // child `field_idx` (`new` put it there; the `# Safety` contract says no
246        // writer was replaced through `field_mut`), which DuckDB allocates with the parent's capacity
247        // (`VectorStructBuffer` constructor, vector_buffer.cpp) and which `new`'s
248        // contract keeps valid; the `# Safety` contract (`write_i8`'s, for the field's
249        // own type) gives `row` within that capacity and a SMALLINT field.
250        unsafe { self.fields[field_idx].write_i16(row, value) };
251    }
252
253    /// Writes an `i32` (INTEGER) value to field `field_idx` at row `row`.
254    ///
255    /// # Safety
256    ///
257    /// See [`write_i8`][Self::write_i8].
258    #[inline]
259    pub unsafe fn write_i32(&mut self, row: usize, field_idx: usize, value: i32) {
260        // SAFETY: `VectorWriter::write_i32` needs `row` within the vector's capacity
261        // and a INTEGER vector. `self.fields[field_idx]` (bounds-checked) wraps STRUCT
262        // child `field_idx` (`new` put it there; the `# Safety` contract says no
263        // writer was replaced through `field_mut`), which DuckDB allocates with the parent's capacity
264        // (`VectorStructBuffer` constructor, vector_buffer.cpp) and which `new`'s
265        // contract keeps valid; the `# Safety` contract (`write_i8`'s, for the field's
266        // own type) gives `row` within that capacity and a INTEGER field.
267        unsafe { self.fields[field_idx].write_i32(row, value) };
268    }
269
270    /// Writes an `i64` (BIGINT) value to field `field_idx` at row `row`.
271    ///
272    /// # Safety
273    ///
274    /// See [`write_i8`][Self::write_i8].
275    #[inline]
276    pub unsafe fn write_i64(&mut self, row: usize, field_idx: usize, value: i64) {
277        // SAFETY: `VectorWriter::write_i64` needs `row` within the vector's capacity
278        // and a BIGINT vector. `self.fields[field_idx]` (bounds-checked) wraps STRUCT
279        // child `field_idx` (`new` put it there; the `# Safety` contract says no
280        // writer was replaced through `field_mut`), which DuckDB allocates with the parent's capacity
281        // (`VectorStructBuffer` constructor, vector_buffer.cpp) and which `new`'s
282        // contract keeps valid; the `# Safety` contract (`write_i8`'s, for the field's
283        // own type) gives `row` within that capacity and a BIGINT field.
284        unsafe { self.fields[field_idx].write_i64(row, value) };
285    }
286
287    /// Writes an `i128` (HUGEINT) value to field `field_idx` at row `row`.
288    ///
289    /// # Safety
290    ///
291    /// See [`write_i8`][Self::write_i8].
292    #[inline]
293    pub unsafe fn write_i128(&mut self, row: usize, field_idx: usize, value: i128) {
294        // SAFETY: `VectorWriter::write_i128` needs `row` within the vector's capacity
295        // and a HUGEINT vector. `self.fields[field_idx]` (bounds-checked) wraps STRUCT
296        // child `field_idx` (`new` put it there; the `# Safety` contract says no
297        // writer was replaced through `field_mut`), which DuckDB allocates with the parent's capacity
298        // (`VectorStructBuffer` constructor, vector_buffer.cpp) and which `new`'s
299        // contract keeps valid; the `# Safety` contract (`write_i8`'s, for the field's
300        // own type) gives `row` within that capacity and a HUGEINT field.
301        unsafe { self.fields[field_idx].write_i128(row, value) };
302    }
303
304    /// Writes a `u8` (UTINYINT) value to field `field_idx` at row `row`.
305    ///
306    /// # Safety
307    ///
308    /// See [`write_i8`][Self::write_i8].
309    #[inline]
310    pub unsafe fn write_u8(&mut self, row: usize, field_idx: usize, value: u8) {
311        // SAFETY: `VectorWriter::write_u8` needs `row` within the vector's capacity
312        // and a UTINYINT vector. `self.fields[field_idx]` (bounds-checked) wraps STRUCT
313        // child `field_idx` (`new` put it there; the `# Safety` contract says no
314        // writer was replaced through `field_mut`), which DuckDB allocates with the parent's capacity
315        // (`VectorStructBuffer` constructor, vector_buffer.cpp) and which `new`'s
316        // contract keeps valid; the `# Safety` contract (`write_i8`'s, for the field's
317        // own type) gives `row` within that capacity and a UTINYINT field.
318        unsafe { self.fields[field_idx].write_u8(row, value) };
319    }
320
321    /// Writes a `u16` (USMALLINT) value to field `field_idx` at row `row`.
322    ///
323    /// # Safety
324    ///
325    /// See [`write_i8`][Self::write_i8].
326    #[inline]
327    pub unsafe fn write_u16(&mut self, row: usize, field_idx: usize, value: u16) {
328        // SAFETY: `VectorWriter::write_u16` needs `row` within the vector's capacity
329        // and a USMALLINT vector. `self.fields[field_idx]` (bounds-checked) wraps STRUCT
330        // child `field_idx` (`new` put it there; the `# Safety` contract says no
331        // writer was replaced through `field_mut`), which DuckDB allocates with the parent's capacity
332        // (`VectorStructBuffer` constructor, vector_buffer.cpp) and which `new`'s
333        // contract keeps valid; the `# Safety` contract (`write_i8`'s, for the field's
334        // own type) gives `row` within that capacity and a USMALLINT field.
335        unsafe { self.fields[field_idx].write_u16(row, value) };
336    }
337
338    /// Writes a `u32` (UINTEGER) value to field `field_idx` at row `row`.
339    ///
340    /// # Safety
341    ///
342    /// See [`write_i8`][Self::write_i8].
343    #[inline]
344    pub unsafe fn write_u32(&mut self, row: usize, field_idx: usize, value: u32) {
345        // SAFETY: `VectorWriter::write_u32` needs `row` within the vector's capacity
346        // and a UINTEGER vector. `self.fields[field_idx]` (bounds-checked) wraps STRUCT
347        // child `field_idx` (`new` put it there; the `# Safety` contract says no
348        // writer was replaced through `field_mut`), which DuckDB allocates with the parent's capacity
349        // (`VectorStructBuffer` constructor, vector_buffer.cpp) and which `new`'s
350        // contract keeps valid; the `# Safety` contract (`write_i8`'s, for the field's
351        // own type) gives `row` within that capacity and a UINTEGER field.
352        unsafe { self.fields[field_idx].write_u32(row, value) };
353    }
354
355    /// Writes a `u64` (UBIGINT) value to field `field_idx` at row `row`.
356    ///
357    /// # Safety
358    ///
359    /// See [`write_i8`][Self::write_i8].
360    #[inline]
361    pub unsafe fn write_u64(&mut self, row: usize, field_idx: usize, value: u64) {
362        // SAFETY: `VectorWriter::write_u64` needs `row` within the vector's capacity
363        // and a UBIGINT vector. `self.fields[field_idx]` (bounds-checked) wraps STRUCT
364        // child `field_idx` (`new` put it there; the `# Safety` contract says no
365        // writer was replaced through `field_mut`), which DuckDB allocates with the parent's capacity
366        // (`VectorStructBuffer` constructor, vector_buffer.cpp) and which `new`'s
367        // contract keeps valid; the `# Safety` contract (`write_i8`'s, for the field's
368        // own type) gives `row` within that capacity and a UBIGINT field.
369        unsafe { self.fields[field_idx].write_u64(row, value) };
370    }
371
372    /// Writes an `f32` (FLOAT) value to field `field_idx` at row `row`.
373    ///
374    /// # Safety
375    ///
376    /// See [`write_i8`][Self::write_i8].
377    #[inline]
378    pub unsafe fn write_f32(&mut self, row: usize, field_idx: usize, value: f32) {
379        // SAFETY: `VectorWriter::write_f32` needs `row` within the vector's capacity
380        // and a FLOAT vector. `self.fields[field_idx]` (bounds-checked) wraps STRUCT
381        // child `field_idx` (`new` put it there; the `# Safety` contract says no
382        // writer was replaced through `field_mut`), which DuckDB allocates with the parent's capacity
383        // (`VectorStructBuffer` constructor, vector_buffer.cpp) and which `new`'s
384        // contract keeps valid; the `# Safety` contract (`write_i8`'s, for the field's
385        // own type) gives `row` within that capacity and a FLOAT field.
386        unsafe { self.fields[field_idx].write_f32(row, value) };
387    }
388
389    /// Writes an `f64` (DOUBLE) value to field `field_idx` at row `row`.
390    ///
391    /// # Safety
392    ///
393    /// See [`write_i8`][Self::write_i8].
394    #[inline]
395    pub unsafe fn write_f64(&mut self, row: usize, field_idx: usize, value: f64) {
396        // SAFETY: `VectorWriter::write_f64` needs `row` within the vector's capacity
397        // and a DOUBLE vector. `self.fields[field_idx]` (bounds-checked) wraps STRUCT
398        // child `field_idx` (`new` put it there; the `# Safety` contract says no
399        // writer was replaced through `field_mut`), which DuckDB allocates with the parent's capacity
400        // (`VectorStructBuffer` constructor, vector_buffer.cpp) and which `new`'s
401        // contract keeps valid; the `# Safety` contract (`write_i8`'s, for the field's
402        // own type) gives `row` within that capacity and a DOUBLE field.
403        unsafe { self.fields[field_idx].write_f64(row, value) };
404    }
405
406    /// Writes an INTERVAL value to field `field_idx` at row `row`.
407    ///
408    /// # Safety
409    ///
410    /// See [`write_i8`][Self::write_i8].
411    #[inline]
412    pub unsafe fn write_interval(&mut self, row: usize, field_idx: usize, value: DuckInterval) {
413        // SAFETY: `VectorWriter::write_interval` needs `row` within the vector's capacity
414        // and a INTERVAL vector. `self.fields[field_idx]` (bounds-checked) wraps STRUCT
415        // child `field_idx` (`new` put it there; the `# Safety` contract says no
416        // writer was replaced through `field_mut`), which DuckDB allocates with the parent's capacity
417        // (`VectorStructBuffer` constructor, vector_buffer.cpp) and which `new`'s
418        // contract keeps valid; the `# Safety` contract (`write_i8`'s, for the field's
419        // own type) gives `row` within that capacity and a INTERVAL field.
420        unsafe { self.fields[field_idx].write_interval(row, value) };
421    }
422
423    /// Writes a `BLOB` (binary) value to field `field_idx` at row `row`.
424    ///
425    /// # Safety
426    ///
427    /// See [`write_i8`][Self::write_i8].
428    ///
429    /// # Panics
430    ///
431    /// Panics if `field_idx >= field_count`, or if `value` is longer than
432    /// [`MAX_STRING_LEN`][crate::vector::string::MAX_STRING_LEN].
433    #[inline]
434    pub unsafe fn write_blob(&mut self, row: usize, field_idx: usize, value: &[u8]) {
435        // SAFETY: `VectorWriter::write_blob` needs `row` within the vector's capacity
436        // and a BLOB vector. `self.fields[field_idx]` (bounds-checked) wraps STRUCT
437        // child `field_idx` (`new` put it there; the `# Safety` contract says no
438        // writer was replaced through `field_mut`), which DuckDB allocates with the parent's capacity
439        // (`VectorStructBuffer` constructor, vector_buffer.cpp) and which `new`'s
440        // contract keeps valid; the `# Safety` contract (`write_i8`'s, for the field's
441        // own type) gives `row` within that capacity and a BLOB field.
442        unsafe { self.fields[field_idx].write_blob(row, value) };
443    }
444
445    /// Writes a `UUID`'s textual 128 bits to field `field_idx` at row `row`.
446    ///
447    /// See [`VectorWriter::write_uuid`][crate::vector::VectorWriter::write_uuid]
448    /// for why this is not the raw `HUGEINT` storage.
449    ///
450    /// # Safety
451    ///
452    /// See [`write_i8`][Self::write_i8].
453    #[inline]
454    pub unsafe fn write_uuid(&mut self, row: usize, field_idx: usize, value: u128) {
455        // SAFETY: `VectorWriter::write_uuid` needs `row` within the vector's capacity
456        // and a UUID vector. `self.fields[field_idx]` (bounds-checked) wraps STRUCT
457        // child `field_idx` (`new` put it there; the `# Safety` contract says no
458        // writer was replaced through `field_mut`), which DuckDB allocates with the parent's capacity
459        // (`VectorStructBuffer` constructor, vector_buffer.cpp) and which `new`'s
460        // contract keeps valid; the `# Safety` contract (`write_i8`'s, for the field's
461        // own type) gives `row` within that capacity and a UUID field.
462        unsafe { self.fields[field_idx].write_uuid(row, value) };
463    }
464
465    /// Writes a VARCHAR string value to field `field_idx` at row `row`.
466    ///
467    /// Alias for [`write_varchar`][Self::write_varchar].
468    ///
469    /// # Safety
470    ///
471    /// See [`write_varchar`][Self::write_varchar].
472    #[inline]
473    pub unsafe fn write_str(&mut self, row: usize, field_idx: usize, value: &str) {
474        // SAFETY: this function's contract is `write_varchar`'s (`row` within
475        // capacity, a VARCHAR field), which is exactly what `write_varchar` needs.
476        unsafe { self.write_varchar(row, field_idx, value) };
477    }
478
479    /// Writes a `DATE` value (days since epoch) to field `field_idx` at row `row`.
480    ///
481    /// Semantic alias for [`write_i32`][Self::write_i32].
482    ///
483    /// # Safety
484    ///
485    /// See [`write_i8`][Self::write_i8].
486    #[inline]
487    pub unsafe fn write_date(&mut self, row: usize, field_idx: usize, days_since_epoch: i32) {
488        // SAFETY: `write_i32` needs `row` within capacity and a field of 4-byte
489        // `int32` rows. A DATE field (this function's contract) is `duckdb_date
490        // {int32_t days}` (duckdb.h), the same physical layout as INTEGER.
491        unsafe { self.write_i32(row, field_idx, days_since_epoch) };
492    }
493
494    /// Writes a `TIMESTAMP` value (microseconds since epoch) to field `field_idx` at row `row`.
495    ///
496    /// Semantic alias for [`write_i64`][Self::write_i64].
497    ///
498    /// # Safety
499    ///
500    /// See [`write_i8`][Self::write_i8].
501    #[inline]
502    pub unsafe fn write_timestamp(
503        &mut self,
504        row: usize,
505        field_idx: usize,
506        micros_since_epoch: i64,
507    ) {
508        // SAFETY: `write_i64` needs `row` within capacity and a field of 8-byte
509        // `int64` rows. A TIMESTAMP field (this function's contract) is
510        // `duckdb_timestamp {int64_t micros}` (duckdb.h), the same physical layout
511        // as BIGINT.
512        unsafe { self.write_i64(row, field_idx, micros_since_epoch) };
513    }
514
515    /// Writes a `TIME` value (microseconds since midnight) to field `field_idx` at row `row`.
516    ///
517    /// Semantic alias for [`write_i64`][Self::write_i64].
518    ///
519    /// # Safety
520    ///
521    /// See [`write_i8`][Self::write_i8]. Also, `micros_since_midnight` must be
522    /// in `0..=86_400_000_000`: see
523    /// [`VectorWriter::write_time`][crate::vector::VectorWriter::write_time],
524    /// whose out-of-range values crash `DuckDB` when it renders them.
525    #[inline]
526    pub unsafe fn write_time(&mut self, row: usize, field_idx: usize, micros_since_midnight: i64) {
527        // SAFETY: `write_i64` needs `row` within capacity and a field of 8-byte
528        // `int64` rows. A TIME field (this function's contract) is `duckdb_time
529        // {int64_t micros}` (duckdb.h), the same physical layout as BIGINT.
530        unsafe { self.write_i64(row, field_idx, micros_since_midnight) };
531    }
532
533    /// Marks the whole struct at row `row` as NULL — the struct itself and
534    /// every field, recursively.
535    ///
536    /// This is what `DuckDB` does internally for a NULL struct row. Marking only
537    /// the fields NULL leaves the row a valid struct of NULLs (`{'a': NULL}`),
538    /// not a NULL; marking only the parent (a bare
539    /// `duckdb_validity_set_row_invalid`) leaves the fields valid, so
540    /// `struct_extract` on the NULL row returns their stale values.
541    ///
542    /// # Safety
543    ///
544    /// - `row` must be within the vector's capacity.
545    #[inline]
546    pub unsafe fn set_row_null(&mut self, row: usize) {
547        // SAFETY: the parent is the valid STRUCT vector passed to `new`, and
548        // `row` is in bounds per caller's contract.
549        unsafe { self.parent.set_null(row) };
550    }
551
552    /// Marks field `field_idx` at row `row` as NULL.
553    ///
554    /// To make the whole struct row NULL use
555    /// [`set_row_null`][Self::set_row_null] instead.
556    ///
557    /// # Safety
558    ///
559    /// - `row` must be within the vector's capacity.
560    /// - No field writer has been replaced through [`field_mut`][Self::field_mut]
561    ///   (by assignment or `std::mem::swap`): the write goes to whatever writer
562    ///   is at `field_idx`, and the other conditions are about field `field_idx`.
563    ///
564    /// # Panics
565    ///
566    /// Panics if `field_idx >= field_count`.
567    #[inline]
568    pub unsafe fn set_null(&mut self, row: usize, field_idx: usize) {
569        // SAFETY: caller guarantees row is in bounds.
570        unsafe { self.fields[field_idx].set_null(row) };
571    }
572
573    /// Marks field `field_idx` at row `row` as valid (non-NULL).
574    ///
575    /// Use this to undo a previous [`set_null`][Self::set_null] call.
576    ///
577    /// # Safety
578    ///
579    /// - `row` must be within the vector's capacity.
580    /// - No field writer has been replaced through [`field_mut`][Self::field_mut]
581    ///   (by assignment or `std::mem::swap`): the write goes to whatever writer
582    ///   is at `field_idx`, and the other conditions are about field `field_idx`.
583    ///
584    /// # Panics
585    ///
586    /// Panics if `field_idx >= field_count`.
587    #[inline]
588    pub unsafe fn set_valid(&mut self, row: usize, field_idx: usize) {
589        // SAFETY: caller guarantees row is in bounds.
590        unsafe { self.fields[field_idx].set_valid(row) };
591    }
592}
593
594#[cfg(test)]
595mod tests {
596    use super::*;
597
598    #[test]
599    fn struct_writer_field_count() {
600        // We can't create a real StructWriter without DuckDB, but we can verify
601        // the Vec-based field storage works correctly.
602        let sw = StructWriter {
603            parent: VectorWriter::detached(),
604            fields: Vec::new(),
605        };
606        assert_eq!(sw.field_count(), 0);
607    }
608
609    #[test]
610    fn size_of_struct_writer() {
611        // StructWriter is the parent VectorWriter plus a Vec<VectorWriter>
612        // (ptr, len, cap).
613        assert_eq!(
614            std::mem::size_of::<StructWriter>(),
615            std::mem::size_of::<VectorWriter>() + 3 * std::mem::size_of::<usize>()
616        );
617    }
618}