Skip to main content

quack_rs/vector/
reader.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 reading from `DuckDB` data vectors.
7//!
8//! [`VectorReader`] provides safe access to the typed data in a `DuckDB` vector
9//! without requiring direct raw pointer manipulation.
10//!
11//! # Pitfalls solved
12//!
13//! - **L5**: Booleans are read as `u8 != 0`, never as `bool`, because `DuckDB`'s
14//!   C API does not guarantee the Rust `bool` invariant (must be 0 or 1).
15//!
16//! # Example
17//!
18//! ```rust,no_run
19//! use quack_rs::vector::VectorReader;
20//! use libduckdb_sys::{duckdb_data_chunk, duckdb_data_chunk_get_vector,
21//!                     duckdb_data_chunk_get_size};
22//!
23//! // Inside a DuckDB aggregate `update` callback:
24//! // let reader = unsafe { VectorReader::new(chunk, 0) };
25//! // for row in 0..reader.row_count() {
26//! //     if reader.is_valid(row) {
27//! //         let val = unsafe { reader.read_i64(row) };
28//! //     }
29//! // }
30//! ```
31
32use libduckdb_sys::{
33    duckdb_data_chunk, duckdb_data_chunk_get_size, duckdb_data_chunk_get_vector, duckdb_vector,
34    duckdb_vector_get_data, duckdb_vector_get_validity, idx_t,
35};
36
37/// A typed reader for a single column in a `DuckDB` data chunk.
38///
39/// `VectorReader` wraps a pointer to a `DuckDB` vector's data buffer and
40/// provides ergonomic, type-checked access methods for common `DuckDB` types.
41///
42/// # Lifetimes
43///
44/// The reader borrows from the data chunk. Do not call `duckdb_destroy_data_chunk`
45/// while a `VectorReader` that references it is live.
46#[derive(Debug)]
47pub struct VectorReader {
48    data: *const u8,
49    validity: *mut u64,
50    row_count: usize,
51}
52
53impl VectorReader {
54    /// Creates a new `VectorReader` for the given column in a data chunk.
55    ///
56    /// # Safety
57    ///
58    /// - `chunk` must be a valid `duckdb_data_chunk` for the duration of this reader's lifetime.
59    /// - `col_idx` must be a valid column index in the chunk.
60    pub unsafe fn new(chunk: duckdb_data_chunk, col_idx: usize) -> Self {
61        // SAFETY: Caller guarantees chunk is valid.
62        let row_count = usize::try_from(unsafe { duckdb_data_chunk_get_size(chunk) }).unwrap_or(0);
63        // SAFETY: col_idx is valid per caller's contract.
64        let vector = unsafe { duckdb_data_chunk_get_vector(chunk, col_idx as idx_t) };
65        // SAFETY: vector is non-null for valid column indices.
66        let data = unsafe { duckdb_vector_get_data(vector) }.cast::<u8>();
67        // SAFETY: may be null if all values are valid (no NULLs); checked in is_valid.
68        let validity = unsafe { duckdb_vector_get_validity(vector) };
69        Self {
70            data,
71            validity,
72            row_count,
73        }
74    }
75
76    /// Creates a `VectorReader` directly from a raw `duckdb_vector` handle.
77    ///
78    /// Use this when you already have a child vector (e.g., from
79    /// [`StructVector::get_child`][crate::vector::complex::StructVector::get_child] or
80    /// [`ListVector::get_child`][crate::vector::complex::ListVector::get_child]).
81    ///
82    /// # Safety
83    ///
84    /// - `vector` must be a valid `duckdb_vector` for the duration of this reader's lifetime.
85    /// - `row_count` must equal the number of valid rows in the vector.
86    pub unsafe fn from_vector(vector: duckdb_vector, row_count: usize) -> Self {
87        // SAFETY: vector is valid per caller's contract.
88        let data = unsafe { duckdb_vector_get_data(vector) }.cast::<u8>();
89        // SAFETY: `duckdb_vector_get_validity` returns null for a null handle and
90        // otherwise reads the vector's validity mask (data_chunk-c.cpp); `# Safety`
91        // clause 1 makes `vector` valid. A null result (all-valid mask, or a
92        // non-flat, non-constant vector) is handled by `is_valid`.
93        let validity = unsafe { duckdb_vector_get_validity(vector) };
94        Self {
95            data,
96            validity,
97            row_count,
98        }
99    }
100
101    /// Returns the number of rows in this vector.
102    #[cfg_attr(test, mutants::skip)]
103    #[must_use]
104    #[inline]
105    pub const fn row_count(&self) -> usize {
106        self.row_count
107    }
108
109    /// Returns `true` if the value at row `idx` is not NULL.
110    ///
111    /// # Safety
112    ///
113    /// `idx` must be less than `self.row_count()`.
114    #[inline]
115    pub unsafe fn is_valid(&self, idx: usize) -> bool {
116        if self.validity.is_null() {
117            return true;
118        }
119        // The bit is tested here, not through `duckdb_validity_row_is_valid`: an
120        // FFI call per row was about a third of a nullable `map1`'s cost, and
121        // `duckdb.h` documents this layout (bit `idx % 64` of word `idx / 64`,
122        // set when the row is valid) as the faster way to read it.
123        // SAFETY: validity is non-null and idx is in bounds per caller's contract,
124        // so word `idx / 64` lies inside the mask.
125        unsafe { (*self.validity.add(idx >> 6) >> (idx & 63)) & 1 != 0 }
126    }
127
128    /// Reads an `i8` (TINYINT) value at row `idx`.
129    ///
130    /// # Safety
131    ///
132    /// - `idx` must be less than `self.row_count()`.
133    /// - The column must contain `TINYINT` data.
134    /// - The value at `idx` must not be NULL (check with [`is_valid`][Self::is_valid]).
135    #[inline]
136    pub const unsafe fn read_i8(&self, idx: usize) -> i8 {
137        // SAFETY: data points to valid TINYINT array, idx is in bounds.
138        unsafe { core::ptr::read_unaligned(self.data.add(idx).cast::<i8>()) }
139    }
140
141    /// Reads an `i16` (SMALLINT) value at row `idx`.
142    ///
143    /// # Safety
144    ///
145    /// - `idx` must be less than `self.row_count()`.
146    /// - The column must contain `SMALLINT` data.
147    #[inline]
148    pub const unsafe fn read_i16(&self, idx: usize) -> i16 {
149        // SAFETY: 2-byte read from valid SMALLINT vector.
150        unsafe { core::ptr::read_unaligned(self.data.add(idx * 2).cast::<i16>()) }
151    }
152
153    /// Reads an `i32` (INTEGER) value at row `idx`.
154    ///
155    /// # Safety
156    ///
157    /// See [`read_i8`][Self::read_i8].
158    #[inline]
159    pub const unsafe fn read_i32(&self, idx: usize) -> i32 {
160        // SAFETY: 4-byte read from valid INTEGER vector.
161        unsafe { core::ptr::read_unaligned(self.data.add(idx * 4).cast::<i32>()) }
162    }
163
164    /// Reads an `i64` (BIGINT / TIMESTAMP) value at row `idx`.
165    ///
166    /// # Safety
167    ///
168    /// See [`read_i8`][Self::read_i8].
169    #[inline]
170    pub const unsafe fn read_i64(&self, idx: usize) -> i64 {
171        // SAFETY: 8-byte read from valid BIGINT/TIMESTAMP vector.
172        unsafe { core::ptr::read_unaligned(self.data.add(idx * 8).cast::<i64>()) }
173    }
174
175    /// Reads a `u8` (UTINYINT) value at row `idx`.
176    ///
177    /// # Safety
178    ///
179    /// See [`read_i8`][Self::read_i8].
180    #[inline]
181    pub const unsafe fn read_u8(&self, idx: usize) -> u8 {
182        // SAFETY: 1-byte read from valid UTINYINT vector.
183        unsafe { *self.data.add(idx) }
184    }
185
186    /// Reads a `u16` (USMALLINT) value at row `idx`.
187    ///
188    /// # Safety
189    ///
190    /// See [`read_i8`][Self::read_i8].
191    #[inline]
192    pub const unsafe fn read_u16(&self, idx: usize) -> u16 {
193        // SAFETY: 2-byte read from valid USMALLINT vector.
194        unsafe { core::ptr::read_unaligned(self.data.add(idx * 2).cast::<u16>()) }
195    }
196
197    /// Reads a `u32` (UINTEGER) value at row `idx`.
198    ///
199    /// # Safety
200    ///
201    /// See [`read_i8`][Self::read_i8].
202    #[inline]
203    pub const unsafe fn read_u32(&self, idx: usize) -> u32 {
204        // SAFETY: 4-byte read from valid UINTEGER vector.
205        unsafe { core::ptr::read_unaligned(self.data.add(idx * 4).cast::<u32>()) }
206    }
207
208    /// Reads a `u64` (UBIGINT) value at row `idx`.
209    ///
210    /// # Safety
211    ///
212    /// See [`read_i8`][Self::read_i8].
213    #[inline]
214    pub const unsafe fn read_u64(&self, idx: usize) -> u64 {
215        // SAFETY: 8-byte read from valid UBIGINT vector.
216        unsafe { core::ptr::read_unaligned(self.data.add(idx * 8).cast::<u64>()) }
217    }
218
219    /// Reads an `f32` (FLOAT) value at row `idx`.
220    ///
221    /// # Safety
222    ///
223    /// See [`read_i8`][Self::read_i8].
224    #[inline]
225    pub const unsafe fn read_f32(&self, idx: usize) -> f32 {
226        // SAFETY: 4-byte read from valid FLOAT vector.
227        unsafe { core::ptr::read_unaligned(self.data.add(idx * 4).cast::<f32>()) }
228    }
229
230    /// Reads an `f64` (DOUBLE) value at row `idx`.
231    ///
232    /// # Safety
233    ///
234    /// See [`read_i8`][Self::read_i8].
235    #[inline]
236    pub const unsafe fn read_f64(&self, idx: usize) -> f64 {
237        // SAFETY: 8-byte read from valid DOUBLE vector.
238        unsafe { core::ptr::read_unaligned(self.data.add(idx * 8).cast::<f64>()) }
239    }
240
241    /// Reads a `bool` (BOOLEAN) value at row `idx`.
242    ///
243    /// # Pitfall L5: Defensive boolean reading
244    ///
245    /// This method reads the underlying byte as `u8` and compares with `!= 0`,
246    /// rather than casting directly to `bool`. `DuckDB`'s C API does not guarantee
247    /// the Rust `bool` invariant (must be exactly 0 or 1), so a direct cast could
248    /// cause undefined behaviour.
249    ///
250    /// # Safety
251    ///
252    /// - `idx` must be less than `self.row_count()`.
253    /// - The column must contain `BOOLEAN` data.
254    #[inline]
255    pub const unsafe fn read_bool(&self, idx: usize) -> bool {
256        // SAFETY: BOOLEAN data is stored as 1 byte per value.
257        // We read as u8 (not bool) to avoid UB if DuckDB sets non-0/1 values.
258        // This is Pitfall L5: always read boolean as u8 then compare != 0.
259        unsafe { *self.data.add(idx) != 0 }
260    }
261
262    /// Reads an `i128` (HUGEINT) value at row `idx`.
263    ///
264    /// `DuckDB` stores HUGEINT as `{ lower: u64, upper: i64 }`, `lower` first,
265    /// each in the target's byte order: 16 bytes per value.
266    ///
267    /// # Safety
268    ///
269    /// - `idx` must be less than `self.row_count()`.
270    /// - The column must contain `HUGEINT` data.
271    /// - The value at `idx` must not be NULL (check with [`is_valid`][Self::is_valid]).
272    #[inline]
273    pub const unsafe fn read_i128(&self, idx: usize) -> i128 {
274        // SAFETY: HUGEINT is stored as { lower: u64, upper: i64 } = 16 bytes.
275        // `lower` is at offset 0 and `upper` at offset 8, each a native-endian integer.
276        let base = unsafe { self.data.add(idx * 16) };
277        // SAFETY: `base` is row `idx`'s 16-byte `duckdb_hugeint` ({lower: u64,
278        // upper: i64}, duckdb.h) in the vector's data buffer, in bounds because
279        // `idx < self.row_count()` (`# Safety` clause 1) and a HUGEINT column
280        // (clause 2) stores 16 bytes per row; `read_unaligned` needs no alignment.
281        let lower = unsafe { core::ptr::read_unaligned(base.cast::<u64>()) };
282        // SAFETY: `base + 8 .. base + 16` is the `upper` half of the same in-bounds
283        // 16-byte value; `read_unaligned` needs no alignment.
284        let upper = unsafe { core::ptr::read_unaligned(base.add(8).cast::<i64>()) };
285        // Widening casts: u64→i128 and i64→i128 are always lossless.
286        #[allow(clippy::cast_lossless)]
287        let result = (upper as i128) << 64 | (lower as i128);
288        result
289    }
290
291    /// Reads a `u128` (UHUGEINT) value at row `idx`.
292    ///
293    /// `DuckDB` stores UHUGEINT as `{ lower: u64, upper: u64 }`, `lower` first,
294    /// each in the target's byte order: 16 bytes per value.
295    ///
296    /// # Safety
297    ///
298    /// - `idx` must be less than `self.row_count()`.
299    /// - The column must contain `UHUGEINT` data.
300    #[inline]
301    pub const unsafe fn read_u128(&self, idx: usize) -> u128 {
302        // SAFETY: UHUGEINT = { lower: u64, upper: u64 } = 16 bytes.
303        let base = unsafe { self.data.add(idx * 16) };
304        // SAFETY: `base` is row `idx`'s 16-byte `duckdb_uhugeint` ({lower: u64,
305        // upper: u64}, duckdb.h) in the vector's data buffer, in bounds because
306        // `idx < self.row_count()` (`# Safety` clause 1) and a UHUGEINT column
307        // (clause 2) stores 16 bytes per row; `read_unaligned` needs no alignment.
308        let lower = unsafe { core::ptr::read_unaligned(base.cast::<u64>()) };
309        // SAFETY: `base + 8 .. base + 16` is the `upper` half of the same in-bounds
310        // 16-byte value; `read_unaligned` needs no alignment.
311        let upper = unsafe { core::ptr::read_unaligned(base.add(8).cast::<u64>()) };
312        ((upper as u128) << 64) | (lower as u128)
313    }
314
315    /// Reads a `TIMESTAMP WITH TIME ZONE` value at row `idx`, as microseconds
316    /// since the Unix epoch in UTC.
317    ///
318    /// # Safety
319    ///
320    /// - `idx` must be less than `self.row_count()`.
321    /// - The column must contain `TIMESTAMPTZ` data.
322    #[inline]
323    pub const unsafe fn read_timestamp_tz(&self, idx: usize) -> i64 {
324        // SAFETY: TIMESTAMPTZ shares TIMESTAMP's i64 storage.
325        unsafe { self.read_i64(idx) }
326    }
327
328    /// Reads a `TIMESTAMP_S` value at row `idx`, as seconds since the epoch.
329    ///
330    /// # Safety
331    ///
332    /// - `idx` must be less than `self.row_count()`.
333    /// - The column must contain `TIMESTAMP_S` data.
334    #[inline]
335    pub const unsafe fn read_timestamp_s(&self, idx: usize) -> i64 {
336        // SAFETY: TIMESTAMP_S is stored as i64 seconds.
337        unsafe { self.read_i64(idx) }
338    }
339
340    /// Reads a `TIMESTAMP_MS` value at row `idx`, as milliseconds since the
341    /// epoch.
342    ///
343    /// # Safety
344    ///
345    /// - `idx` must be less than `self.row_count()`.
346    /// - The column must contain `TIMESTAMP_MS` data.
347    #[inline]
348    pub const unsafe fn read_timestamp_ms(&self, idx: usize) -> i64 {
349        // SAFETY: TIMESTAMP_MS is stored as i64 milliseconds.
350        unsafe { self.read_i64(idx) }
351    }
352
353    /// Reads a `TIMESTAMP_NS` value at row `idx`, as nanoseconds since the
354    /// epoch.
355    ///
356    /// # Safety
357    ///
358    /// - `idx` must be less than `self.row_count()`.
359    /// - The column must contain `TIMESTAMP_NS` data.
360    #[inline]
361    pub const unsafe fn read_timestamp_ns(&self, idx: usize) -> i64 {
362        // SAFETY: TIMESTAMP_NS is stored as i64 nanoseconds.
363        unsafe { self.read_i64(idx) }
364    }
365
366    /// Reads a `TIMESTAMPTZ_NS` value at row `idx`, as nanoseconds since the
367    /// epoch (`DuckDB` 2.0.0+).
368    ///
369    /// # Safety
370    ///
371    /// - `idx` must be less than `self.row_count()`.
372    /// - The column must contain `TIMESTAMPTZ_NS` data.
373    #[inline]
374    pub const unsafe fn read_timestamp_tz_ns(&self, idx: usize) -> i64 {
375        // SAFETY: TIMESTAMPTZ_NS is stored as i64 nanoseconds
376        // (`timestamp_tz_ns_t` wraps a `timestamp_ns_t`).
377        unsafe { self.read_i64(idx) }
378    }
379
380    /// Reads a `TIME WITH TIME ZONE` value at row `idx` as `DuckDB`'s packed
381    /// 64-bit representation.
382    ///
383    /// Decode it with
384    /// [`datetime::time_tz_from_bits`][crate::datetime::time_tz_from_bits].
385    ///
386    /// # Safety
387    ///
388    /// - `idx` must be less than `self.row_count()`.
389    /// - The column must contain `TIMETZ` data.
390    #[inline]
391    pub const unsafe fn read_time_tz(&self, idx: usize) -> u64 {
392        // SAFETY: TIMETZ is stored as a 64-bit packed value.
393        unsafe { self.read_u64(idx) }
394    }
395
396    /// Reads a `DECIMAL` value at row `idx` as its unscaled integer.
397    ///
398    /// `DuckDB` stores a `DECIMAL` in the narrowest integer that fits its
399    /// declared width — `i16` up to 4 digits, `i32` up to 9, `i64` up to 18, and
400    /// `i128` up to 38 — so `width` must be the column's declared width. Get it
401    /// from [`LogicalType::decimal_width`][crate::types::LogicalType::decimal_width].
402    ///
403    /// The represented number is `result / 10^scale`.
404    ///
405    /// # Safety
406    ///
407    /// - `idx` must be less than `self.row_count()`.
408    /// - The column must contain `DECIMAL` data with exactly this `width`.
409    #[inline]
410    pub const unsafe fn read_decimal(&self, idx: usize, width: u8) -> i128 {
411        // SAFETY: the caller guarantees `width` matches the column's declared
412        // width, which fixes the physical storage type.
413        unsafe {
414            if width <= 4 {
415                self.read_i16(idx) as i128
416            } else if width <= 9 {
417                self.read_i32(idx) as i128
418            } else if width <= 18 {
419                self.read_i64(idx) as i128
420            } else {
421                self.read_i128(idx)
422            }
423        }
424    }
425
426    /// Returns `true` if `idx` addresses a row of this vector.
427    ///
428    /// Every `read_*` method requires `idx < row_count()`; this is the check to
429    /// pair with them when the index comes from somewhere other than a
430    /// `0..row_count()` loop.
431    #[must_use]
432    #[inline]
433    pub const fn contains(&self, idx: usize) -> bool {
434        idx < self.row_count
435    }
436
437    /// Reads a VARCHAR value at row `idx`.
438    ///
439    /// Returns an empty string if the data is not valid UTF-8 or if the internal
440    /// string pointer is null.
441    ///
442    /// # Pitfall P7
443    ///
444    /// `DuckDB` stores strings in a 16-byte `duckdb_string_t` with two formats
445    /// (inline for ≤ 12 bytes, pointer otherwise). This method handles both.
446    ///
447    /// # Safety
448    ///
449    /// - `idx` must be less than `self.row_count()`.
450    /// - The column must contain `VARCHAR` data.
451    /// - Row `idx` must not be NULL (check [`is_valid`][Self::is_valid] first).
452    ///   `DuckDB` does not reset the payload of a NULL row, so it can still
453    ///   hold the pointer-format entry of a string from an earlier chunk,
454    ///   whose memory may since have been freed or reused.
455    /// - For pointer-format strings, the pointed-to heap memory must be valid
456    ///   for the lifetime of the returned `&str`.
457    pub unsafe fn read_str(&self, idx: usize) -> &str {
458        // SAFETY: Caller guarantees data is a VARCHAR vector and idx is in bounds.
459        unsafe { crate::vector::string::read_duck_string(self.data, idx) }
460    }
461
462    /// Reads a `BLOB` (binary) value at row `idx`.
463    ///
464    /// `DuckDB` stores BLOBs using the same 16-byte `duckdb_string_t` layout as
465    /// VARCHAR (inline for ≤12 bytes, pointer for larger values). The returned
466    /// slice borrows from the vector's data buffer.
467    ///
468    /// The bytes are returned without UTF-8 validation.
469    ///
470    /// # Safety
471    ///
472    /// - `idx` must be less than `self.row_count()`.
473    /// - The column must contain `BLOB` data.
474    /// - Row `idx` must not be NULL (check [`is_valid`][Self::is_valid] first).
475    ///   `DuckDB` does not reset the payload of a NULL row, so it can still
476    ///   hold the pointer-format entry of a string from an earlier chunk,
477    ///   whose memory may since have been freed or reused.
478    /// - The pointed-to memory must be valid for the lifetime of the returned slice.
479    pub unsafe fn read_blob(&self, idx: usize) -> &[u8] {
480        // SAFETY: BLOB uses the same duckdb_string_t layout as VARCHAR, so
481        // `self.data` is a valid buffer for `read_duck_blob` and `idx` is in
482        // bounds (clauses 1-2); clause 3 keeps both the vector's buffer and any
483        // heap data alive for the returned slice, which is bound to `&self`.
484        unsafe { crate::vector::string::read_duck_blob(self.data, idx) }
485    }
486
487    /// Reads a `UUID` value at row `idx` as a `u128`.
488    ///
489    /// Reads the UUID's **textual** 128 bits — the value the column renders,
490    /// and what every Rust `Uuid` type holds.
491    ///
492    /// A `UUID` column is physically a `HUGEINT`, but `DuckDB` stores it with
493    /// the top bit flipped so that signed integer ordering matches UUID string
494    /// ordering, so the raw storage of
495    /// `'11111111-2222-3333-4444-555555555555'` is `0x9111...`, not `0x1111...`.
496    /// This undoes that. Use [`read_i128`][Self::read_i128] for the raw storage,
497    /// and [`uuid_from_storage`][crate::vector::uuid_from_storage] to convert.
498    ///
499    /// # Safety
500    ///
501    /// - `idx` must be less than `self.row_count()`.
502    /// - The column must contain `UUID` data.
503    #[inline]
504    pub const unsafe fn read_uuid(&self, idx: usize) -> u128 {
505        // SAFETY: UUID is stored as HUGEINT; undo DuckDB's top-bit flip.
506        unsafe { crate::vector::uuid::uuid_from_storage(self.read_i128(idx)) }
507    }
508
509    /// Reads a `DATE` value at row `idx` as days since the Unix epoch.
510    ///
511    /// `DuckDB` stores DATE as a 4-byte `i32` representing the number of days
512    /// since 1970-01-01. This is a semantic alias for [`read_i32`][Self::read_i32].
513    ///
514    /// # Safety
515    ///
516    /// - `idx` must be less than `self.row_count()`.
517    /// - The column must contain `DATE` data.
518    #[inline]
519    pub const unsafe fn read_date(&self, idx: usize) -> i32 {
520        // SAFETY: DATE is stored as i32 (days since epoch).
521        unsafe { self.read_i32(idx) }
522    }
523
524    /// Reads a `TIMESTAMP` value at row `idx` as microseconds since the Unix epoch.
525    ///
526    /// `DuckDB` stores TIMESTAMP as an 8-byte `i64` representing microseconds
527    /// since 1970-01-01 00:00:00 UTC. This is a semantic alias for
528    /// [`read_i64`][Self::read_i64].
529    ///
530    /// # Safety
531    ///
532    /// - `idx` must be less than `self.row_count()`.
533    /// - The column must contain `TIMESTAMP` data.
534    #[inline]
535    pub const unsafe fn read_timestamp(&self, idx: usize) -> i64 {
536        // SAFETY: TIMESTAMP is stored as i64 (microseconds since epoch).
537        unsafe { self.read_i64(idx) }
538    }
539
540    /// Reads a `TIME` value at row `idx` as microseconds since midnight.
541    ///
542    /// `DuckDB` stores TIME as an 8-byte `i64` representing microseconds since
543    /// midnight. This is a semantic alias for [`read_i64`][Self::read_i64].
544    ///
545    /// # Safety
546    ///
547    /// - `idx` must be less than `self.row_count()`.
548    /// - The column must contain `TIME` data.
549    #[inline]
550    pub const unsafe fn read_time(&self, idx: usize) -> i64 {
551        // SAFETY: TIME is stored as i64 (microseconds since midnight).
552        unsafe { self.read_i64(idx) }
553    }
554
555    /// Reads an `INTERVAL` value at row `idx`.
556    ///
557    /// Returns a [`DuckInterval`][crate::interval::DuckInterval] struct.
558    ///
559    /// # Pitfall P8
560    ///
561    /// The `INTERVAL` struct is 16 bytes: `{ months: i32, days: i32, micros: i64 }`.
562    /// This method handles the layout correctly using [`read_interval_at`][crate::interval::read_interval_at].
563    ///
564    /// # Safety
565    ///
566    /// - `idx` must be less than `self.row_count()`.
567    /// - The column must contain `INTERVAL` data.
568    #[inline]
569    pub const unsafe fn read_interval(&self, idx: usize) -> crate::interval::DuckInterval {
570        // SAFETY: data is a valid INTERVAL vector and idx is in bounds.
571        unsafe { crate::interval::read_interval_at(self.data, idx) }
572    }
573}
574
575#[cfg(test)]
576mod tests {
577    use super::*;
578
579    /// Pitfall L5: `read_bool` must treat any non-zero byte as `true` rather
580    /// than reinterpret the byte as a Rust `bool` (UB for anything but 0/1).
581    /// The reader is built over a local buffer, so this calls the real
582    /// `read_bool` — and under Miri, would flag a `bool` transmute of `2`.
583    #[test]
584    fn read_bool_treats_every_non_zero_byte_as_true() {
585        let data: [u8; 4] = [0, 1, 2, 255];
586        let reader = VectorReader {
587            data: data.as_ptr(),
588            validity: std::ptr::null_mut(),
589            row_count: data.len(),
590        };
591        // SAFETY: every index is within `data`, which outlives `reader`.
592        let read: Vec<bool> = (0..data.len())
593            .map(|i| unsafe { reader.read_bool(i) })
594            .collect();
595        assert_eq!(read, [false, true, true, true]);
596    }
597
598    #[test]
599    fn row_count_is_zero_for_empty_state() {
600        // This exercises the struct layout; actual DuckDB integration is in tests/
601        let reader = VectorReader {
602            data: std::ptr::null(),
603            validity: std::ptr::null_mut(),
604            row_count: 0,
605        };
606        assert_eq!(reader.row_count(), 0);
607    }
608
609    #[test]
610    fn contains_bounds_checks_against_row_count() {
611        let reader = VectorReader {
612            data: std::ptr::null(),
613            validity: std::ptr::null_mut(),
614            row_count: 3,
615        };
616        assert!(reader.contains(0));
617        assert!(reader.contains(2));
618        assert!(!reader.contains(3));
619        assert!(!reader.contains(usize::MAX));
620    }
621
622    #[test]
623    fn decimal_width_thresholds_match_duckdb_storage() {
624        // DuckDB picks the physical type from the declared width:
625        // <=4 -> INT16, <=9 -> INT32, <=18 -> INT64, <=38 -> INT128
626        // (duckdb/common/types/decimal.hpp). Reading with the wrong width reads
627        // the wrong number of bytes, so pin the boundaries.
628        let mut buf = [0u8; 16];
629        buf[..2].copy_from_slice(&(-1234_i16).to_ne_bytes());
630        let reader = VectorReader {
631            data: buf.as_ptr(),
632            validity: std::ptr::null_mut(),
633            row_count: 1,
634        };
635        // SAFETY: `buf` holds one INT16 at index 0.
636        assert_eq!(unsafe { reader.read_decimal(0, 4) }, -1234);
637
638        let mut buf = [0u8; 16];
639        buf[..4].copy_from_slice(&(-123_456_789_i32).to_ne_bytes());
640        let reader = VectorReader {
641            data: buf.as_ptr(),
642            validity: std::ptr::null_mut(),
643            row_count: 1,
644        };
645        // SAFETY: `buf` holds one INT32 at index 0.
646        assert_eq!(unsafe { reader.read_decimal(0, 9) }, -123_456_789);
647
648        let mut buf = [0u8; 16];
649        buf[..8].copy_from_slice(&(-1_234_567_890_123_456_789_i64).to_ne_bytes());
650        let reader = VectorReader {
651            data: buf.as_ptr(),
652            validity: std::ptr::null_mut(),
653            row_count: 1,
654        };
655        // SAFETY: `buf` holds one INT64 at index 0.
656        assert_eq!(
657            unsafe { reader.read_decimal(0, 18) },
658            -1_234_567_890_123_456_789
659        );
660
661        let value: i128 = -170_141_183_460_469_231_731_687_303_715_884_105_727;
662        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
663        let buf = hugeint_bytes(value as u64, (value >> 64) as u64);
664        let reader = VectorReader {
665            data: buf.as_ptr(),
666            validity: std::ptr::null_mut(),
667            row_count: 1,
668        };
669        // SAFETY: `buf` holds one INT128 at index 0.
670        assert_eq!(unsafe { reader.read_decimal(0, 38) }, value);
671    }
672
673    /// A `duckdb_hugeint` / `duckdb_uhugeint` as `DuckDB` lays it out: `lower`
674    /// then `upper`, each in the target's byte order.
675    fn hugeint_bytes(lower: u64, upper: u64) -> [u8; 16] {
676        let mut buf = [0u8; 16];
677        buf[..8].copy_from_slice(&lower.to_ne_bytes());
678        buf[8..].copy_from_slice(&upper.to_ne_bytes());
679        buf
680    }
681
682    #[test]
683    fn u128_reads_the_lower_then_the_upper_half() {
684        let value: u128 = (0xdead_beef_u128 << 64) | 0x1234_5678;
685        let buf = hugeint_bytes(0x1234_5678, 0xdead_beef);
686        let reader = VectorReader {
687            data: buf.as_ptr(),
688            validity: std::ptr::null_mut(),
689            row_count: 1,
690        };
691        // SAFETY: `buf` holds one UHUGEINT at index 0.
692        assert_eq!(unsafe { reader.read_u128(0) }, value);
693    }
694
695    #[test]
696    fn is_valid_when_validity_null() {
697        // When validity is null, all rows are considered valid
698        let reader = VectorReader {
699            data: std::ptr::null(),
700            validity: std::ptr::null_mut(),
701            row_count: 5,
702        };
703        // SAFETY: row 0 is in bounds (row_count = 5), validity is null (all valid)
704        assert!(unsafe { reader.is_valid(0) });
705        assert!(unsafe { reader.is_valid(4) });
706    }
707
708    /// `is_valid` tests a bit itself instead of calling
709    /// `duckdb_validity_row_is_valid`. Held to the expression `duckdb.h` gives for
710    /// `duckdb_vector_get_validity` (`mask[row / 64] & (1 << (row % 64))`) over three
711    /// words, with masks that set and clear every position, so a wrong shift, word
712    /// or polarity fails. The pointer arithmetic is also what Miri checks.
713    #[test]
714    fn is_valid_follows_the_documented_mask_layout() {
715        let masks: [[u64; 3]; 6] = [
716            [u64::MAX; 3],
717            [0; 3],
718            [
719                0xAAAA_AAAA_AAAA_AAAA,
720                0x5555_5555_5555_5555,
721                0xAAAA_AAAA_AAAA_AAAA,
722            ],
723            [1, 1 << 63, 1],
724            [u64::MAX ^ (1 << 63), 1 << 63, u64::MAX ^ 1],
725            [
726                0x0123_4567_89AB_CDEF,
727                0xFEDC_BA98_7654_3210,
728                0x8000_0000_0000_0001,
729            ],
730        ];
731        for words in masks {
732            let mut mask = words; // the reader aliases `mask`; the oracle reads `words`
733            let reader = VectorReader {
734                data: std::ptr::null(),
735                validity: mask.as_mut_ptr(),
736                row_count: 192,
737            };
738            for row in 0..192 {
739                let documented = words[row / 64] & (1 << (row % 64)) != 0;
740                // SAFETY: `row < 192` is inside the three words of `mask`.
741                let got = unsafe { reader.is_valid(row) };
742                assert_eq!(got, documented, "row {row}, mask {words:x?}");
743            }
744        }
745    }
746}