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}