quack_rs/vector/validity.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//! Validity bitmap helpers for `DuckDB` NULL tracking.
7//!
8//! `DuckDB` tracks NULL values using a packed validity bitmap. Each row's validity
9//! is represented by a single bit in a `u64` array. This module provides a safe
10//! wrapper that encapsulates the bit manipulation.
11//!
12//! # Pitfall L4: `ensure_validity_writable`
13//!
14//! When writing NULL values, `duckdb_vector_get_validity` returns NULL for a
15//! vector that has no validity mask yet (the usual state of a vector no NULL
16//! has been written to) unless `duckdb_vector_ensure_validity_writable` has
17//! been called first — and `duckdb_validity_set_row_invalid` silently ignores a
18//! NULL mask, so the NULL would be dropped.
19//! [`ValidityBitmap::ensure_writable`] wraps this requirement so it cannot be
20//! forgotten.
21
22use libduckdb_sys::{
23 duckdb_validity_row_is_valid, duckdb_validity_set_row_invalid, duckdb_validity_set_row_valid,
24 duckdb_vector, duckdb_vector_ensure_validity_writable, duckdb_vector_get_validity, idx_t,
25};
26
27/// A wrapper around a `DuckDB` validity bitmap for reading or writing NULL flags.
28///
29/// Obtain a writable instance via [`ValidityBitmap::ensure_writable`]. For
30/// read-only access, use [`ValidityBitmap::get_read_only`].
31///
32/// # Safety invariants
33///
34/// The underlying `duckdb_vector` must remain valid for the lifetime `'v` of
35/// this wrapper. Do not call `duckdb_destroy_data_chunk` while a `ValidityBitmap`
36/// that references the vector is live.
37#[derive(Debug)]
38pub struct ValidityBitmap<'v> {
39 validity: *mut u64,
40 _phantom: std::marker::PhantomData<&'v mut duckdb_vector>,
41}
42
43impl ValidityBitmap<'_> {
44 /// Ensures the validity bitmap is writable and returns a [`ValidityBitmap`].
45 ///
46 /// This calls `duckdb_vector_ensure_validity_writable` before
47 /// `duckdb_vector_get_validity`, which is required before writing NULL flags.
48 ///
49 /// # Pitfall L4
50 ///
51 /// Calling `duckdb_vector_get_validity` without first calling
52 /// `duckdb_vector_ensure_validity_writable` returns NULL when the vector
53 /// has no mask yet, and NULLs written through that are silently dropped.
54 ///
55 /// # Safety
56 ///
57 /// `vector` must be a valid `DuckDB` vector handle obtained from a data chunk
58 /// within the current callback invocation. The vector must not be destroyed
59 /// while the returned `ValidityBitmap` is live. If `vector` lies inside the
60 /// child of a `LIST` or `MAP` vector — is that child, or a STRUCT field or
61 /// ARRAY element vector below it with no other `LIST` or `MAP` in between —
62 /// the bitmap must not be used after that `LIST` or `MAP` is grown with a
63 /// `reserve`, which reallocates the validity buffer of every such vector.
64 pub unsafe fn ensure_writable(vector: duckdb_vector) -> Self {
65 // SAFETY: `vector` is a valid DuckDB vector handle. This call marks the
66 // vector's validity buffer as writable and allocates it if it doesn't exist.
67 unsafe { duckdb_vector_ensure_validity_writable(vector) };
68 // SAFETY: The bitmap was just ensured to be writable and allocated.
69 let validity = unsafe { duckdb_vector_get_validity(vector) };
70 Self {
71 validity,
72 _phantom: std::marker::PhantomData,
73 }
74 }
75
76 /// Gets the validity bitmap for read-only NULL checks.
77 ///
78 /// # Safety
79 ///
80 /// `vector` must be a valid `DuckDB` vector handle. The returned pointer may
81 /// be null if the vector has no validity bitmap (all rows are valid).
82 pub unsafe fn get_read_only(vector: duckdb_vector) -> Self {
83 // SAFETY: Caller guarantees `vector` is valid.
84 let validity = unsafe { duckdb_vector_get_validity(vector) };
85 Self {
86 validity,
87 _phantom: std::marker::PhantomData,
88 }
89 }
90
91 /// Returns `true` if the row at `idx` is valid (non-NULL).
92 ///
93 /// If the validity bitmap pointer is null (all rows are valid), always returns
94 /// `true`.
95 ///
96 /// # Safety
97 ///
98 /// `idx` must be less than the number of rows in the vector.
99 #[inline]
100 pub unsafe fn row_is_valid(&self, idx: idx_t) -> bool {
101 if self.validity.is_null() {
102 return true;
103 }
104 // SAFETY: `validity` is non-null and `idx` is in bounds per the caller's contract.
105 unsafe { duckdb_validity_row_is_valid(self.validity, idx) }
106 }
107
108 /// Marks the row at `idx` as NULL (invalid).
109 ///
110 /// This touches only this one mask. For a `STRUCT` or `ARRAY` vector, use
111 /// [`VectorWriter::set_null`][crate::vector::VectorWriter::set_null]
112 /// instead, which also nulls the children as `DuckDB` expects.
113 ///
114 /// # Safety
115 ///
116 /// - This bitmap must have been created via [`ensure_writable`][ValidityBitmap::ensure_writable].
117 /// - `idx` must be less than the number of rows in the vector.
118 #[inline]
119 pub unsafe fn set_row_invalid(&mut self, idx: idx_t) {
120 debug_assert!(
121 !self.validity.is_null(),
122 "set_row_invalid called on a non-writable bitmap"
123 );
124 // SAFETY: Bitmap is writable (ensured in constructor) and idx is in bounds.
125 unsafe { duckdb_validity_set_row_invalid(self.validity, idx) };
126 }
127
128 /// Marks the row at `idx` as valid (non-NULL).
129 ///
130 /// # Safety
131 ///
132 /// - This bitmap must have been created via [`ensure_writable`][ValidityBitmap::ensure_writable].
133 /// - `idx` must be less than the number of rows in the vector.
134 #[inline]
135 pub unsafe fn set_row_valid(&mut self, idx: idx_t) {
136 debug_assert!(
137 !self.validity.is_null(),
138 "set_row_valid called on a non-writable bitmap"
139 );
140 // SAFETY: Bitmap is writable and idx is in bounds.
141 unsafe { duckdb_validity_set_row_valid(self.validity, idx) };
142 }
143
144 /// Returns the raw validity bitmap pointer.
145 ///
146 /// This is an escape hatch for code that needs direct bitmap access.
147 /// Prefer the safe methods on this type when possible.
148 #[must_use]
149 #[inline]
150 pub const fn as_raw(&self) -> *mut u64 {
151 self.validity
152 }
153}
154
155#[cfg(test)]
156mod tests {
157 // Note: validity bitmap tests that require a real DuckDB vector are in
158 // tests/ffi_roundtrip/validity_api.rs and nested_validity.rs. Unit tests
159 // here cover the struct size and null-bitmap logic.
160
161 #[test]
162 fn read_only_with_null_ptr() {
163 // When the validity pointer is null, all rows are considered valid.
164 use super::ValidityBitmap;
165 use libduckdb_sys::duckdb_vector;
166 // We cannot easily construct a real vector here without a full DuckDB connection,
167 // but we can test the null-pointer code path using get_read_only on a null vector.
168 // This is a known-unsafe call but acceptable in a controlled test.
169 // Instead, test the invariant: if validity ptr is null, row_is_valid returns true.
170 let bm = ValidityBitmap {
171 validity: std::ptr::null_mut(),
172 _phantom: std::marker::PhantomData::<&mut duckdb_vector>,
173 };
174 // SAFETY: idx 0 is vacuously valid when bitmap is null.
175 assert!(unsafe { bm.row_is_valid(0) });
176 }
177}