Skip to main content

quack_rs/vector/
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//! Safe typed writing to `DuckDB` result vectors.
7//!
8//! [`VectorWriter`] provides safe methods for writing typed values and NULL
9//! flags to a `DuckDB` output vector from within a `finalize` callback.
10//!
11//! # Pitfall L4: `ensure_validity_writable`
12//!
13//! When writing NULL values, you must call `duckdb_vector_ensure_validity_writable`
14//! before `duckdb_vector_get_validity`. A vector with no NULLs yet usually has no
15//! validity mask at all, and then `get_validity` returns NULL; the
16//! `duckdb_validity_set_row_*` functions return early on a NULL mask, so the
17//! NULL is **silently dropped** and the row reads back as a valid value.
18//!
19//! [`VectorWriter::set_null`] calls `ensure_validity_writable` automatically.
20//!
21//! # NULLs in nested vectors
22//!
23//! Marking a `STRUCT` or `ARRAY` row NULL also marks its children NULL — every
24//! field of the struct row, every element of the array row, recursively —
25//! exactly as `DuckDB`'s internal `FlatVector::SetNull` does. Without that,
26//! `struct_extract(s, 'a')` on a NULL row returns whatever was last written to
27//! field `a`. `LIST` and `MAP` children are not touched, matching `DuckDB`.
28
29use libduckdb_sys::{
30    duckdb_validity_set_row_invalid, duckdb_validity_set_row_valid, duckdb_vector,
31    duckdb_vector_assign_string_element_len, duckdb_vector_ensure_validity_writable,
32    duckdb_vector_get_data, duckdb_vector_get_validity, idx_t,
33};
34
35use super::nested_null::{self, NullTarget};
36use super::string::check_string_len;
37use crate::error::ExtensionError;
38
39/// A typed writer for a `DuckDB` output vector in a `finalize` callback.
40///
41/// # Example
42///
43/// ```rust,no_run
44/// use quack_rs::vector::VectorWriter;
45/// use libduckdb_sys::duckdb_vector;
46///
47/// // Inside finalize:
48/// // let mut writer = unsafe { VectorWriter::new(result_vector) };
49/// // for row in 0..count {
50/// //     if let Some(val) = compute_result(row) {
51/// //         unsafe { writer.write_i64(row, val) };
52/// //     } else {
53/// //         unsafe { writer.set_null(row) };
54/// //     }
55/// // }
56/// ```
57#[derive(Debug)]
58pub struct VectorWriter {
59    vector: duckdb_vector,
60    data: *mut u8,
61    /// Lazily-resolved NULL-writing state; `None` until the first
62    /// `set_null` / `set_valid`. Boxed so a writer that never writes a NULL
63    /// stays three words and allocates nothing.
64    nulls: Option<Box<NullState>>,
65}
66
67/// What [`VectorWriter`] resolves once, on its first NULL write.
68#[derive(Debug)]
69struct NullState {
70    /// The writable validity bitmap.
71    ///
72    /// `duckdb_vector_ensure_validity_writable` allocates the mask on first use
73    /// and is a no-op afterwards, and the resulting pointer is stable until the
74    /// vector's buffers are reallocated — which only a `reserve` on a `LIST` or
75    /// `MAP` whose child holds this vector (directly, or through STRUCT fields
76    /// and ARRAY elements) does, and which `from_vector`'s contract rules out
77    /// while the writer is in use. Caching it turns "two FFI calls per NULL" into "two
78    /// FFI calls per vector", which matters when a column is mostly NULL: a full
79    /// 2048-row vector went from 4096 calls to 2.
80    validity: *mut u64,
81    /// Child masks a NULL must also clear (STRUCT fields, ARRAY elements),
82    /// resolved on the first `set_null`. `None` until then; empty for a
83    /// vector that is neither STRUCT nor ARRAY. Resolving walks the type once
84    /// per writer rather than once per NULL row.
85    nested: Option<Vec<NullTarget>>,
86}
87
88impl VectorWriter {
89    /// Creates a new `VectorWriter` for the given result vector.
90    ///
91    /// # Safety
92    ///
93    /// `vector` must be a valid `DuckDB` output vector obtained in a `finalize`
94    /// callback. The vector must not be destroyed while this writer is live.
95    pub unsafe fn new(vector: duckdb_vector) -> Self {
96        // SAFETY: Caller guarantees vector is valid.
97        let data = unsafe { duckdb_vector_get_data(vector) }.cast::<u8>();
98        Self {
99            vector,
100            data,
101            nulls: None,
102        }
103    }
104
105    /// Creates a `VectorWriter` directly from a raw `duckdb_vector` handle.
106    ///
107    /// Use this when you need to write into a child vector (e.g., a STRUCT field
108    /// or LIST element vector) obtained from
109    /// [`StructVector::get_child`][crate::vector::complex::StructVector::get_child] or
110    /// [`ListVector::get_child`][crate::vector::complex::ListVector::get_child].
111    ///
112    /// # Safety
113    ///
114    /// `vector` must be a valid, writable `duckdb_vector`. The vector must not be
115    /// destroyed while this writer is live. If `vector` lies inside the child
116    /// of a `LIST` or `MAP` vector — is that child, or a STRUCT field or ARRAY
117    /// element vector below it with no other `LIST` or `MAP` in between — the
118    /// writer must not be used after that `LIST` or `MAP` is grown with a
119    /// `reserve`: growing reallocates the data and validity buffers of every
120    /// such vector, and the writer caches pointers to both. (Measured by
121    /// `tests/ffi_roundtrip/nested_reserve.rs`.)
122    pub unsafe fn from_vector(vector: duckdb_vector) -> Self {
123        // SAFETY: caller guarantees vector is valid.
124        let data = unsafe { duckdb_vector_get_data(vector) }.cast::<u8>();
125        Self {
126            vector,
127            data,
128            nulls: None,
129        }
130    }
131
132    /// Writes an `i8` (TINYINT) value at row `idx`.
133    ///
134    /// # Safety
135    ///
136    /// - `idx` must be within the vector's capacity.
137    /// - The vector must have `TINYINT` type.
138    #[inline]
139    pub const unsafe fn write_i8(&mut self, idx: usize, value: i8) {
140        // SAFETY: data points to a valid writable TINYINT array. idx is in bounds.
141        unsafe { core::ptr::write_unaligned(self.data.add(idx).cast::<i8>(), value) };
142    }
143
144    /// Writes an `i16` (SMALLINT) value at row `idx`.
145    ///
146    /// # Safety
147    ///
148    /// See [`write_i8`][Self::write_i8].
149    #[inline]
150    pub const unsafe fn write_i16(&mut self, idx: usize, value: i16) {
151        // SAFETY: 2-byte aligned write to valid SMALLINT vector.
152        unsafe { core::ptr::write_unaligned(self.data.add(idx * 2).cast::<i16>(), value) };
153    }
154
155    /// Writes an `i32` (INTEGER) value at row `idx`.
156    ///
157    /// # Safety
158    ///
159    /// See [`write_i8`][Self::write_i8].
160    #[inline]
161    pub const unsafe fn write_i32(&mut self, idx: usize, value: i32) {
162        // SAFETY: 4-byte aligned write to valid INTEGER vector.
163        unsafe { core::ptr::write_unaligned(self.data.add(idx * 4).cast::<i32>(), value) };
164    }
165
166    /// Writes an `i64` (BIGINT / TIMESTAMP) value at row `idx`.
167    ///
168    /// # Safety
169    ///
170    /// See [`write_i8`][Self::write_i8].
171    #[inline]
172    pub const unsafe fn write_i64(&mut self, idx: usize, value: i64) {
173        // SAFETY: 8-byte aligned write to valid BIGINT vector.
174        unsafe { core::ptr::write_unaligned(self.data.add(idx * 8).cast::<i64>(), value) };
175    }
176
177    /// Writes a `u8` (UTINYINT) value at row `idx`.
178    ///
179    /// # Safety
180    ///
181    /// See [`write_i8`][Self::write_i8].
182    #[inline]
183    pub const unsafe fn write_u8(&mut self, idx: usize, value: u8) {
184        // SAFETY: 1-byte write to valid UTINYINT vector.
185        unsafe { *self.data.add(idx) = value };
186    }
187
188    /// Writes a `u32` (UINTEGER) value at row `idx`.
189    ///
190    /// # Safety
191    ///
192    /// See [`write_i8`][Self::write_i8].
193    #[inline]
194    pub const unsafe fn write_u32(&mut self, idx: usize, value: u32) {
195        // SAFETY: 4-byte aligned write to valid UINTEGER vector.
196        unsafe { core::ptr::write_unaligned(self.data.add(idx * 4).cast::<u32>(), value) };
197    }
198
199    /// Writes a `u64` (UBIGINT) value at row `idx`.
200    ///
201    /// # Safety
202    ///
203    /// See [`write_i8`][Self::write_i8].
204    #[inline]
205    pub const unsafe fn write_u64(&mut self, idx: usize, value: u64) {
206        // SAFETY: 8-byte aligned write to valid UBIGINT vector.
207        unsafe { core::ptr::write_unaligned(self.data.add(idx * 8).cast::<u64>(), value) };
208    }
209
210    /// Writes an `f32` (FLOAT) value at row `idx`.
211    ///
212    /// # Safety
213    ///
214    /// See [`write_i8`][Self::write_i8].
215    #[inline]
216    pub const unsafe fn write_f32(&mut self, idx: usize, value: f32) {
217        // SAFETY: 4-byte aligned write to valid FLOAT vector.
218        unsafe { core::ptr::write_unaligned(self.data.add(idx * 4).cast::<f32>(), value) };
219    }
220
221    /// Writes an `f64` (DOUBLE) value at row `idx`.
222    ///
223    /// # Safety
224    ///
225    /// See [`write_i8`][Self::write_i8].
226    #[inline]
227    pub const unsafe fn write_f64(&mut self, idx: usize, value: f64) {
228        // SAFETY: 8-byte aligned write to valid DOUBLE vector.
229        unsafe { core::ptr::write_unaligned(self.data.add(idx * 8).cast::<f64>(), value) };
230    }
231
232    /// Writes a `bool` (BOOLEAN) value at row `idx`.
233    ///
234    /// Booleans are stored as a single byte: `1` for `true`, `0` for `false`.
235    ///
236    /// # Safety
237    ///
238    /// - `idx` must be within the vector's capacity.
239    /// - The vector must have `BOOLEAN` type.
240    #[inline]
241    pub unsafe fn write_bool(&mut self, idx: usize, value: bool) {
242        // SAFETY: BOOLEAN stored as 1 byte.
243        unsafe { *self.data.add(idx) = u8::from(value) };
244    }
245
246    /// Writes an `i128` (HUGEINT) value at row `idx`.
247    ///
248    /// `DuckDB` stores HUGEINT as `{ lower: u64, upper: i64 }`, `lower` first,
249    /// each in the target's byte order: 16 bytes per value.
250    ///
251    /// # Safety
252    ///
253    /// - `idx` must be within the vector's capacity.
254    /// - The vector must have `HUGEINT` type.
255    #[inline]
256    pub const unsafe fn write_i128(&mut self, idx: usize, value: i128) {
257        // SAFETY: HUGEINT = { lower: u64, upper: i64 } = 16 bytes.
258        let base = unsafe { self.data.add(idx * 16) };
259        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
260        let lower = value as u64;
261        #[allow(clippy::cast_possible_truncation)]
262        let upper = (value >> 64) as i64;
263        // SAFETY: `base` and `base + 8` are the `lower`/`upper` halves of row
264        // `idx`'s 16-byte `duckdb_hugeint` ({uint64_t lower; int64_t upper},
265        // duckdb.h) in `self.data`, the flat data buffer the constructor's contract
266        // keeps valid. Both 8-byte writes stay in bounds because `idx` is within
267        // the vector's capacity (`# Safety` clause 1) and a HUGEINT vector (clause
268        // 2) stores 16 bytes per row; `write_unaligned` needs no alignment.
269        unsafe {
270            core::ptr::write_unaligned(base.cast::<u64>(), lower);
271            core::ptr::write_unaligned(base.add(8).cast::<i64>(), upper);
272        }
273    }
274
275    /// Writes a `u16` (USMALLINT) value at row `idx`.
276    ///
277    /// # Safety
278    ///
279    /// See [`write_i8`][Self::write_i8].
280    #[inline]
281    pub const unsafe fn write_u16(&mut self, idx: usize, value: u16) {
282        // SAFETY: 2-byte aligned write to valid USMALLINT vector.
283        unsafe { core::ptr::write_unaligned(self.data.add(idx * 2).cast::<u16>(), value) };
284    }
285
286    /// Writes a VARCHAR string value at row `idx`.
287    ///
288    /// This uses `duckdb_vector_assign_string_element_len` which handles both
289    /// the inline (≤12 bytes) and pointer (>12 bytes) storage formats
290    /// automatically. `DuckDB` manages the memory for the string data.
291    ///
292    /// # Panics
293    ///
294    /// Panics if `value` is longer than
295    /// [`MAX_STRING_LEN`][crate::vector::string::MAX_STRING_LEN] (4 GiB − 1),
296    /// the most a `DuckDB` string can hold. Writing it anyway would store the
297    /// length modulo 2^32 — a silently truncated value. Inside
298    /// [`scalar_callback!`][crate::scalar_callback] and the typed scalar
299    /// constructors the panic becomes a SQL error; use
300    /// [`try_write_varchar`][Self::try_write_varchar] to handle it yourself.
301    ///
302    /// # Safety
303    ///
304    /// - `idx` must be within the vector's capacity.
305    /// - The vector must have `VARCHAR` type.
306    pub unsafe fn write_varchar(&mut self, idx: usize, value: &str) {
307        // SAFETY: forwarded from this method's own contract.
308        if let Err(e) = unsafe { self.try_write_varchar(idx, value) } {
309            panic!("write_varchar: {e}");
310        }
311    }
312
313    /// Writes a VARCHAR string value at row `idx`, or returns an error — writing
314    /// nothing — if `value` is longer than
315    /// [`MAX_STRING_LEN`][crate::vector::string::MAX_STRING_LEN].
316    ///
317    /// # Errors
318    ///
319    /// Returns an error if `value.len()` exceeds `MAX_STRING_LEN`.
320    ///
321    /// # Safety
322    ///
323    /// See [`write_varchar`][Self::write_varchar].
324    pub unsafe fn try_write_varchar(
325        &mut self,
326        idx: usize,
327        value: &str,
328    ) -> Result<(), ExtensionError> {
329        // SAFETY: forwarded from this method's own contract.
330        unsafe { self.try_assign_string(idx, value.as_bytes()) }
331    }
332
333    /// Stores `bytes` as the `duckdb_string_t` at row `idx` after checking its
334    /// length. `DuckDB` copies the bytes.
335    ///
336    /// # Safety
337    ///
338    /// `idx` must be within the vector's capacity, and the vector must be
339    /// `VARCHAR` (with `bytes` valid UTF-8) or `BLOB`.
340    unsafe fn try_assign_string(&mut self, idx: usize, bytes: &[u8]) -> Result<(), ExtensionError> {
341        check_string_len(bytes.len())?;
342        // SAFETY: self.vector is valid and idx in bounds per the caller's
343        // contract; the length fits in `u32`, so DuckDB's narrowing is exact.
344        unsafe {
345            duckdb_vector_assign_string_element_len(
346                self.vector,
347                idx as idx_t,
348                bytes.as_ptr().cast::<std::os::raw::c_char>(),
349                bytes.len() as idx_t,
350            );
351        }
352        Ok(())
353    }
354
355    /// Writes a `DATE` value at row `idx` as days since the Unix epoch.
356    ///
357    /// `DuckDB` stores DATE as a 4-byte `i32`. This is a semantic alias for
358    /// [`write_i32`][Self::write_i32].
359    ///
360    /// # Safety
361    ///
362    /// - `idx` must be within the vector's capacity.
363    /// - The vector must have `DATE` type.
364    #[inline]
365    pub const unsafe fn write_date(&mut self, idx: usize, days_since_epoch: i32) {
366        // SAFETY: DATE is stored as i32.
367        unsafe { self.write_i32(idx, days_since_epoch) };
368    }
369
370    /// Writes a `TIMESTAMP` value at row `idx` as microseconds since the Unix epoch.
371    ///
372    /// `DuckDB` stores TIMESTAMP as an 8-byte `i64`. This is a semantic alias for
373    /// [`write_i64`][Self::write_i64]. The value is not range-checked: one below
374    /// `DuckDB`'s earliest timestamp (other than `-infinity`, `-i64::MAX`) makes
375    /// every later cast or rendering of the row fail with "Date out of range in
376    /// timestamp conversion". The same holds for the other timestamp writers.
377    ///
378    /// # Safety
379    ///
380    /// - `idx` must be within the vector's capacity.
381    /// - The vector must have `TIMESTAMP` type.
382    #[inline]
383    pub const unsafe fn write_timestamp(&mut self, idx: usize, micros_since_epoch: i64) {
384        // SAFETY: TIMESTAMP is stored as i64.
385        unsafe { self.write_i64(idx, micros_since_epoch) };
386    }
387
388    /// Writes a `TIME` value at row `idx` as microseconds since midnight.
389    ///
390    /// `DuckDB` stores TIME as an 8-byte `i64`. This is a semantic alias for
391    /// [`write_i64`][Self::write_i64].
392    ///
393    /// # Safety
394    ///
395    /// - `idx` must be within the vector's capacity.
396    /// - The vector must have `TIME` type.
397    /// - `micros_since_midnight` must be in `0..=86_400_000_000` (`00:00:00`
398    ///   to `24:00:00`). `DuckDB` does not check a `TIME` it reads back: when
399    ///   it renders one, `i64::MIN` crashes the process (a segfault in
400    ///   `Time::Convert`, checked on 1.5.5), `i64::MAX` raises an internal
401    ///   error, and `-1` renders as `00:00:00.00000/`.
402    #[inline]
403    pub const unsafe fn write_time(&mut self, idx: usize, micros_since_midnight: i64) {
404        // SAFETY: TIME is stored as i64.
405        unsafe { self.write_i64(idx, micros_since_midnight) };
406    }
407
408    /// Writes an INTERVAL value at row `idx`.
409    ///
410    /// `DuckDB` stores INTERVAL as `{ months: i32, days: i32, micros: i64 }` in a
411    /// 16-byte layout. This method writes all three components at the correct offsets.
412    ///
413    /// # Safety
414    ///
415    /// - `idx` must be within the vector's capacity.
416    /// - The vector must have `INTERVAL` type.
417    #[inline]
418    pub const unsafe fn write_interval(
419        &mut self,
420        idx: usize,
421        value: crate::interval::DuckInterval,
422    ) {
423        // SAFETY: INTERVAL = { months: i32 @ 0, days: i32 @ 4, micros: i64 @ 8 } = 16 bytes.
424        let base = unsafe { self.data.add(idx * 16) };
425        // SAFETY: `base`, `base + 4` and `base + 8` are the `months`, `days` and
426        // `micros` fields of row `idx`'s 16-byte `duckdb_interval` ({int32_t;
427        // int32_t; int64_t}, duckdb.h) in `self.data`, the flat data buffer the
428        // constructor's contract keeps valid. All writes stay in bounds because
429        // `idx` is within the vector's capacity (`# Safety` clause 1) and an
430        // INTERVAL vector (clause 2) stores 16 bytes per row; `write_unaligned`
431        // needs no alignment.
432        unsafe {
433            core::ptr::write_unaligned(base.cast::<i32>(), value.months);
434            core::ptr::write_unaligned(base.add(4).cast::<i32>(), value.days);
435            core::ptr::write_unaligned(base.add(8).cast::<i64>(), value.micros);
436        }
437    }
438
439    /// Writes a `BLOB` (binary) value at row `idx`.
440    ///
441    /// This uses the same underlying storage as VARCHAR — `DuckDB` stores BLOBs
442    /// using `duckdb_vector_assign_string_element_len`, which copies the data.
443    ///
444    /// # Panics
445    ///
446    /// Panics if `value` is longer than
447    /// [`MAX_STRING_LEN`][crate::vector::string::MAX_STRING_LEN]; see
448    /// [`write_varchar`][Self::write_varchar]. Use
449    /// [`try_write_blob`][Self::try_write_blob] to handle it yourself.
450    ///
451    /// # Safety
452    ///
453    /// - `idx` must be within the vector's capacity.
454    /// - The vector must have `BLOB` type.
455    pub unsafe fn write_blob(&mut self, idx: usize, value: &[u8]) {
456        // SAFETY: forwarded from this method's own contract.
457        if let Err(e) = unsafe { self.try_write_blob(idx, value) } {
458            panic!("write_blob: {e}");
459        }
460    }
461
462    /// Writes a `BLOB` value at row `idx`, or returns an error — writing
463    /// nothing — if `value` is longer than
464    /// [`MAX_STRING_LEN`][crate::vector::string::MAX_STRING_LEN].
465    ///
466    /// # Errors
467    ///
468    /// Returns an error if `value.len()` exceeds `MAX_STRING_LEN`.
469    ///
470    /// # Safety
471    ///
472    /// See [`write_blob`][Self::write_blob].
473    pub unsafe fn try_write_blob(
474        &mut self,
475        idx: usize,
476        value: &[u8],
477    ) -> Result<(), ExtensionError> {
478        // SAFETY: forwarded from this method's own contract.
479        unsafe { self.try_assign_string(idx, value) }
480    }
481
482    /// Writes a `UUID` value at row `idx`.
483    ///
484    /// Writes `bits` — the UUID's **textual** 128 bits, as every Rust `Uuid`
485    /// type holds them — at row `idx`.
486    ///
487    /// A `UUID` column is physically a `HUGEINT`, but `DuckDB` stores it with
488    /// the top bit flipped so that signed integer ordering matches UUID string
489    /// ordering. This applies that flip, so the value you pass is the value the
490    /// column renders. Use [`write_i128`][Self::write_i128] to write the raw
491    /// storage instead, and [`uuid_to_storage`][crate::vector::uuid_to_storage]
492    /// to convert between the two.
493    ///
494    /// # Safety
495    ///
496    /// - `idx` must be within the vector's capacity.
497    /// - The vector must have `UUID` type.
498    #[inline]
499    pub const unsafe fn write_uuid(&mut self, idx: usize, bits: u128) {
500        // SAFETY: UUID is stored as HUGEINT, with DuckDB's top-bit flip applied.
501        unsafe { self.write_i128(idx, crate::vector::uuid::uuid_to_storage(bits)) };
502    }
503
504    /// Writes a VARCHAR string value at row `idx`.
505    ///
506    /// This is an alias for [`write_varchar`][VectorWriter::write_varchar] provided
507    /// for discoverability — extension authors often look for `write_str` first.
508    ///
509    /// # Safety
510    ///
511    /// - `idx` must be within the vector's capacity.
512    /// - The vector must have `VARCHAR` type.
513    #[inline]
514    pub unsafe fn write_str(&mut self, idx: usize, value: &str) {
515        // SAFETY: Delegates to write_varchar; same contract.
516        unsafe { self.write_varchar(idx, value) };
517    }
518
519    /// Writes a `u128` (UHUGEINT) value at row `idx`.
520    ///
521    /// `DuckDB` stores UHUGEINT as `{ lower: u64, upper: u64 }`, `lower` first,
522    /// each in the target's byte order: 16 bytes per value.
523    ///
524    /// # Safety
525    ///
526    /// - `idx` must be within the vector's capacity.
527    /// - The vector must have `UHUGEINT` type.
528    #[inline]
529    pub const unsafe fn write_u128(&mut self, idx: usize, value: u128) {
530        // SAFETY: UHUGEINT = { lower: u64, upper: u64 } = 16 bytes.
531        let base = unsafe { self.data.add(idx * 16) };
532        #[allow(clippy::cast_possible_truncation)]
533        let lower = value as u64;
534        #[allow(clippy::cast_possible_truncation)]
535        let upper = (value >> 64) as u64;
536        // SAFETY: `base` and `base + 8` are the `lower`/`upper` halves of row
537        // `idx`'s 16-byte `duckdb_uhugeint` ({uint64_t lower; uint64_t upper},
538        // duckdb.h) in `self.data`, the flat data buffer the constructor's contract
539        // keeps valid. Both 8-byte writes stay in bounds because `idx` is within
540        // the vector's capacity (`# Safety` clause 1) and a UHUGEINT vector (clause
541        // 2) stores 16 bytes per row; `write_unaligned` needs no alignment.
542        unsafe {
543            core::ptr::write_unaligned(base.cast::<u64>(), lower);
544            core::ptr::write_unaligned(base.add(8).cast::<u64>(), upper);
545        }
546    }
547
548    /// Writes a `TIMESTAMP WITH TIME ZONE` value at row `idx`, as microseconds
549    /// since the Unix epoch in UTC.
550    ///
551    /// `TIMESTAMPTZ` shares `TIMESTAMP`'s 8-byte `i64` storage; only the logical
552    /// type differs.
553    ///
554    /// # Safety
555    ///
556    /// - `idx` must be within the vector's capacity.
557    /// - The vector must have `TIMESTAMPTZ` type.
558    #[inline]
559    pub const unsafe fn write_timestamp_tz(&mut self, idx: usize, micros_since_epoch: i64) {
560        // SAFETY: TIMESTAMPTZ is stored as i64 microseconds.
561        unsafe { self.write_i64(idx, micros_since_epoch) };
562    }
563
564    /// Writes a `TIMESTAMP_S` value at row `idx`, as seconds since the epoch.
565    ///
566    /// # Safety
567    ///
568    /// - `idx` must be within the vector's capacity.
569    /// - The vector must have `TIMESTAMP_S` type.
570    #[inline]
571    pub const unsafe fn write_timestamp_s(&mut self, idx: usize, seconds_since_epoch: i64) {
572        // SAFETY: TIMESTAMP_S is stored as i64 seconds.
573        unsafe { self.write_i64(idx, seconds_since_epoch) };
574    }
575
576    /// Writes a `TIMESTAMP_MS` value at row `idx`, as milliseconds since the
577    /// epoch.
578    ///
579    /// # Safety
580    ///
581    /// - `idx` must be within the vector's capacity.
582    /// - The vector must have `TIMESTAMP_MS` type.
583    #[inline]
584    pub const unsafe fn write_timestamp_ms(&mut self, idx: usize, millis_since_epoch: i64) {
585        // SAFETY: TIMESTAMP_MS is stored as i64 milliseconds.
586        unsafe { self.write_i64(idx, millis_since_epoch) };
587    }
588
589    /// Writes a `TIMESTAMP_NS` value at row `idx`, as nanoseconds since the
590    /// epoch.
591    ///
592    /// # Safety
593    ///
594    /// - `idx` must be within the vector's capacity.
595    /// - The vector must have `TIMESTAMP_NS` type.
596    #[inline]
597    pub const unsafe fn write_timestamp_ns(&mut self, idx: usize, nanos_since_epoch: i64) {
598        // SAFETY: TIMESTAMP_NS is stored as i64 nanoseconds.
599        unsafe { self.write_i64(idx, nanos_since_epoch) };
600    }
601
602    /// Writes a `TIMESTAMPTZ_NS` value at row `idx`, as nanoseconds since the
603    /// epoch (`DuckDB` 2.0.0+).
604    ///
605    /// # Safety
606    ///
607    /// - `idx` must be within the vector's capacity.
608    /// - The vector must have `TIMESTAMPTZ_NS` type.
609    #[inline]
610    pub const unsafe fn write_timestamp_tz_ns(&mut self, idx: usize, nanos_since_epoch: i64) {
611        // SAFETY: TIMESTAMPTZ_NS is stored as i64 nanoseconds
612        // (`timestamp_tz_ns_t` wraps a `timestamp_ns_t`).
613        unsafe { self.write_i64(idx, nanos_since_epoch) };
614    }
615
616    /// Writes a `TIME WITH TIME ZONE` value at row `idx`.
617    ///
618    /// `bits` is `DuckDB`'s packed representation; build one with
619    /// [`datetime::time_tz_bits`][crate::datetime::time_tz_bits] rather than
620    /// assembling it by hand. `DuckDB` does not check it: an encoding with a
621    /// time past `24:00:00` or an offset past `±15:59:59` renders as garbage
622    /// (`u64::MAX` as `b}:25:11.627775-4644:20:16`).
623    ///
624    /// # Safety
625    ///
626    /// - `idx` must be within the vector's capacity.
627    /// - The vector must have `TIMETZ` type.
628    #[inline]
629    pub const unsafe fn write_time_tz(&mut self, idx: usize, bits: u64) {
630        // SAFETY: TIMETZ is stored as a 64-bit packed value.
631        unsafe { self.write_u64(idx, bits) };
632    }
633
634    /// Writes a `DECIMAL` value at row `idx` from its unscaled representation.
635    ///
636    /// `DuckDB` stores a `DECIMAL` in the narrowest integer that fits its
637    /// declared width — `i16` up to 4 digits, `i32` up to 9, `i64` up to 18, and
638    /// `i128` beyond — so the width must match the column's type. Get it from
639    /// [`LogicalType::decimal_width`][crate::types::LogicalType::decimal_width].
640    ///
641    /// # Safety
642    ///
643    /// - `idx` must be within the vector's capacity.
644    /// - The vector must have `DECIMAL` type with exactly this `width`.
645    #[inline]
646    pub const unsafe fn write_decimal(&mut self, idx: usize, width: u8, unscaled: i128) {
647        // SAFETY: the caller guarantees `width` matches the column's declared
648        // width, which fixes the physical storage type.
649        unsafe {
650            #[allow(clippy::cast_possible_truncation)]
651            if width <= 4 {
652                self.write_i16(idx, unscaled as i16);
653            } else if width <= 9 {
654                self.write_i32(idx, unscaled as i32);
655            } else if width <= 18 {
656                self.write_i64(idx, unscaled as i64);
657            } else {
658                self.write_i128(idx, unscaled);
659            }
660        }
661    }
662
663    /// Marks row `idx` as NULL in the output vector.
664    ///
665    /// For a `STRUCT` vector this also marks row `idx` NULL in every field,
666    /// recursively; for an `ARRAY` vector of size `n`, child rows
667    /// `idx * n .. idx * n + n`. See the
668    /// [module docs](crate::vector::writer#nulls-in-nested-vectors).
669    /// [`set_valid`][Self::set_valid] undoes all of it.
670    ///
671    /// # Pitfall L4: `ensure_validity_writable`
672    ///
673    /// This method calls `duckdb_vector_ensure_validity_writable` before
674    /// `duckdb_vector_get_validity`, which is required before writing any NULL
675    /// flags. Without it, a vector that has no mask yet yields a NULL mask
676    /// pointer and the NULL is silently dropped.
677    ///
678    /// # Safety
679    ///
680    /// - `idx` must be within the vector's capacity.
681    pub unsafe fn set_null(&mut self, idx: usize) {
682        // SAFETY: self.vector is valid per constructor's contract.
683        let validity = unsafe { self.writable_validity() };
684        // `duckdb_vector_get_validity` has no mask to give for a vector that is
685        // not flat or constant (a sliced or dictionary vector); the C function
686        // this replaced returned early on a null mask, and so does this.
687        debug_assert!(
688            !validity.is_null(),
689            "set_null on a vector with no validity mask"
690        );
691        if validity.is_null() {
692            return;
693        }
694        // Clears bit `idx % 64` of word `idx / 64`, which is all
695        // `duckdb_validity_set_row_invalid` does, without the FFI call (see
696        // `VectorReader::is_valid`).
697        // SAFETY: validity is now initialized and idx is in bounds per caller's
698        // contract, so word `idx / 64` lies inside the mask.
699        unsafe { *validity.add(idx >> 6) &= !(1_u64 << (idx & 63)) };
700        // SAFETY: self.vector is valid; idx is in bounds per caller's contract.
701        unsafe { self.clear_nested(idx..idx + 1) };
702    }
703
704    /// Marks every row in `range` as NULL.
705    ///
706    /// Equivalent to calling [`set_null`][Self::set_null] for each index, but
707    /// resolves the validity bitmap once.
708    ///
709    /// # Safety
710    ///
711    /// Every index in `range` must be within the vector's capacity.
712    pub unsafe fn set_null_range(&mut self, range: core::ops::Range<usize>) {
713        if range.is_empty() {
714            return;
715        }
716        // SAFETY: self.vector is valid per constructor's contract.
717        let validity = unsafe { self.writable_validity() };
718        for idx in range.clone() {
719            // SAFETY: idx is in bounds per caller's contract.
720            unsafe { duckdb_validity_set_row_invalid(validity, idx as idx_t) };
721        }
722        // SAFETY: self.vector is valid; range is in bounds per caller's contract.
723        unsafe { self.clear_nested(range) };
724    }
725
726    /// Marks `rows` NULL in every STRUCT field / ARRAY element below this
727    /// vector, mirroring `DuckDB`'s `FlatVector::SetNull`.
728    ///
729    /// # Safety
730    ///
731    /// `self.vector` must still be a valid, flat, writable vector and every
732    /// index in `rows` within its capacity.
733    unsafe fn clear_nested(&mut self, rows: core::ops::Range<usize>) {
734        let vector = self.vector;
735        // Every caller resolved the validity mask first, so this is `Some`.
736        let Some(state) = self.nulls.as_deref_mut() else {
737            return;
738        };
739        let targets = state
740            .nested
741            // SAFETY: `vector` is valid, flat and writable per this function's
742            // contract.
743            .get_or_insert_with(|| unsafe { nested_null::resolve(vector) });
744        for target in targets.iter() {
745            // SAFETY: `rows` is in bounds per this function's contract.
746            unsafe { target.clear(rows.clone()) };
747        }
748    }
749
750    /// Resolves (once) and returns the writable validity bitmap pointer.
751    ///
752    /// # Pitfall L4: `ensure_validity_writable`
753    ///
754    /// For a vector with no mask yet, `duckdb_vector_get_validity` returns NULL
755    /// (writes through which are silently ignored) until
756    /// `duckdb_vector_ensure_validity_writable` has allocated the mask. This
757    /// does both, then caches the result — `EnsureWritable` is a no-op after the
758    /// first call and the pointer is stable until the vector's buffers are
759    /// reallocated (see the `validity` field of `NullState`).
760    ///
761    /// # Safety
762    ///
763    /// `self.vector` must still be a valid, flat, writable vector.
764    unsafe fn writable_validity(&mut self) -> *mut u64 {
765        let vector = self.vector;
766        self.nulls
767            .get_or_insert_with(|| {
768                // SAFETY: `vector` is valid per constructor's contract.
769                unsafe { duckdb_vector_ensure_validity_writable(vector) };
770                // SAFETY: the mask was just allocated, so the pointer is usable.
771                let validity = unsafe { duckdb_vector_get_validity(vector) };
772                Box::new(NullState {
773                    validity,
774                    nested: None,
775                })
776            })
777            .validity
778    }
779
780    /// Marks row `idx` as valid (non-NULL) in the output vector.
781    ///
782    /// Use this to undo a previous [`set_null`][Self::set_null] call for a row,
783    /// or to explicitly mark a row as valid after writing its value.
784    ///
785    /// If the row is NULL, this also marks valid everything
786    /// [`set_null`][Self::set_null] marked NULL below it — every field of a
787    /// `STRUCT` row and every element of an `ARRAY` row, recursively — so
788    /// that values written there afterwards are read. Write any field or
789    /// element NULLs *after* this call. If the row is already valid, nothing
790    /// below it is touched, so marking a row valid after writing its fields
791    /// keeps any field NULLs.
792    ///
793    /// Like [`set_null`][Self::set_null], this calls `ensure_validity_writable`
794    /// before modifying the validity bitmap.
795    ///
796    /// # Safety
797    ///
798    /// - `idx` must be within the vector's capacity.
799    pub unsafe fn set_valid(&mut self, idx: usize) {
800        // SAFETY: self.vector is valid per constructor's contract.
801        let validity = unsafe { self.writable_validity() };
802        // SAFETY: validity is initialized and idx is in bounds per caller's contract.
803        let was_null =
804            !unsafe { libduckdb_sys::duckdb_validity_row_is_valid(validity, idx as idx_t) };
805        // SAFETY: validity is now initialized and idx is in bounds per caller's contract.
806        unsafe {
807            duckdb_validity_set_row_valid(validity, idx as idx_t);
808        }
809        if was_null {
810            // SAFETY: self.vector is valid; idx is in bounds per caller's contract.
811            unsafe { self.restore_nested(idx..idx + 1) };
812        }
813    }
814
815    /// Marks `rows` valid in every STRUCT field / ARRAY element below this
816    /// vector: the inverse of [`clear_nested`][Self::clear_nested].
817    ///
818    /// # Safety
819    ///
820    /// As for [`clear_nested`][Self::clear_nested].
821    unsafe fn restore_nested(&mut self, rows: core::ops::Range<usize>) {
822        let vector = self.vector;
823        // Every caller resolved the validity mask first, so this is `Some`.
824        let Some(state) = self.nulls.as_deref_mut() else {
825            return;
826        };
827        let targets = state
828            .nested
829            // SAFETY: `vector` is valid, flat and writable per this function's
830            // contract.
831            .get_or_insert_with(|| unsafe { nested_null::resolve(vector) });
832        for target in targets.iter() {
833            // SAFETY: `rows` is in bounds per this function's contract.
834            unsafe { target.restore(rows.clone()) };
835        }
836    }
837
838    /// Returns the underlying raw vector handle.
839    #[must_use]
840    #[inline]
841    pub const fn as_raw(&self) -> duckdb_vector {
842        self.vector
843    }
844
845    /// A writer attached to no vector, for layout tests that never write.
846    #[cfg(test)]
847    pub(crate) const fn detached() -> Self {
848        Self {
849            vector: core::ptr::null_mut(),
850            data: core::ptr::null_mut(),
851            nulls: None,
852        }
853    }
854}
855
856#[cfg(test)]
857mod tests {
858    // Functional tests for VectorWriter require a live DuckDB instance and are
859    // located in tests/integration_test.rs. Unit tests here verify the struct
860    // layout and any pure-Rust logic.
861
862    #[test]
863    fn size_of_vector_writer() {
864        use super::VectorWriter;
865        use std::mem::size_of;
866        // vector + data + the boxed, lazily-resolved NULL state (validity
867        // pointer and nested masks).
868        assert_eq!(size_of::<VectorWriter>(), 3 * size_of::<usize>());
869    }
870}