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}