quack_rs/value/bits.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//! `BIT` and `BIGNUM` values.
7//!
8//! # Why the C getters are never called on an arbitrary value
9//!
10//! `duckdb_get_bit` and `duckdb_get_bignum` (`duckdb_value-c.cpp`, identical
11//! in 1.4.4, 1.5.6 and 2.0.0 apart from a `malloc` null check 2.0 added) run
12//! `DefaultCastAs(BIT | BIGNUM)` and then `StringValue::Get` with no `try`.
13//! The cast throws for a value that does not convert (`'abc'`, a `BLOB`, an
14//! infinite `DOUBLE`) and `StringValue::Get` throws for a SQL `NULL`; either
15//! exception reaches Rust and aborts the process. A null handle is
16//! dereferenced. So the getters here only ever hand `DuckDB` a non-null,
17//! non-`NULL` value whose type is already the target: the value itself, or a
18//! cast copy made by [`Value::try_cast`], which cannot throw.
19//!
20//! # Why the constructors validate
21//!
22//! `duckdb_create_bit` and `duckdb_create_bignum` copy whatever bytes they
23//! are given. A `BIT` with no data byte or a padding count above 7, or a
24//! `BIGNUM` with an empty magnitude, is a value `DuckDB` cannot use: rendering
25//! the `BIGNUM` throws (`Bignum::GetByteArray`: "Invalid blob size"), a `BIT`
26//! with padding 9 makes `Bit::ToString` allocate a length that wrapped below
27//! zero, and one holding only its padding byte makes it write 8 characters
28//! into a 0-byte buffer. A leading zero byte or a "negative zero" breaks the
29//! canonical form `Bignum::Verify` asserts (debug builds) and `DuckDB`'s
30//! byte-wise comparisons rely on. [`Value::bit`] and [`Value::bignum`] build
31//! only well-formed values.
32
33use libduckdb_sys::{
34 duckdb_bignum, duckdb_bit, duckdb_create_bignum, duckdb_create_bit, duckdb_free,
35 duckdb_get_bignum, duckdb_get_bit, idx_t,
36};
37
38use super::Value;
39use crate::error::ExtensionError;
40use crate::types::{LogicalType, TypeId};
41
42/// The largest `BIGNUM` magnitude `DuckDB` stores, in bytes
43/// (`Bignum::MAX_DATA_SIZE`): the 3-byte header holds the length in 23 bits.
44pub(super) const BIGNUM_MAX_BYTES: usize = 8_388_607;
45
46/// `bits` (first = leftmost) in `DuckDB`'s `BIT` layout: a byte holding the
47/// number of padding bits, then the bits right-aligned in whole bytes, with
48/// the padding bits at the front of the first data byte set to 1
49/// (`Bit::Finalize`). `None` for no bits: SQL has no empty `BIT`.
50pub(super) fn encode_bits(bits: &[bool]) -> Option<Vec<u8>> {
51 if bits.is_empty() {
52 return None;
53 }
54 let padding = (8 - bits.len() % 8) % 8;
55 let mut out = Vec::with_capacity(1 + (padding + bits.len()) / 8);
56 // `padding` is below 8.
57 out.push(u8::try_from(padding).ok()?);
58 let mut byte = 0_u8;
59 let mut filled = 0;
60 for bit in std::iter::repeat_n(true, padding).chain(bits.iter().copied()) {
61 // `* 2 + bit` rather than `<< 1 | bit`, whose `|` -> `^` mutant is the
62 // same program (the low bit is always 0 there) and so could never be
63 // killed. `byte` is at most 127 before its eighth bit, so this cannot
64 // overflow.
65 byte = byte * 2 + u8::from(bit);
66 filled += 1;
67 if filled == 8 {
68 out.push(byte);
69 byte = 0;
70 filled = 0;
71 }
72 }
73 Some(out)
74}
75
76/// Whether `bytes` are a `BIT` payload `DuckDB` can read: a padding count of
77/// at most 7 followed by at least one data byte. `Bit::ToString` and
78/// `Bit::BitLength` assume both without checking.
79pub(super) const fn bit_layout_ok(bytes: &[u8]) -> bool {
80 matches!(bytes.split_first(), Some((&padding, data)) if padding <= 7 && !data.is_empty())
81}
82
83/// The bits of a `BIT` value's bytes, or `None` when the bytes are not a
84/// well-formed `BIT` ([`bit_layout_ok`]). The padding bits' own values are
85/// ignored, as `Bit::ToString` ignores them.
86pub(super) fn decode_bits(bytes: &[u8]) -> Option<Vec<bool>> {
87 if !bit_layout_ok(bytes) {
88 return None;
89 }
90 let (&padding, data) = bytes.split_first()?;
91 Some(
92 data.iter()
93 .flat_map(|&byte| (0..8).rev().map(move |i| byte & (1 << i) != 0))
94 .skip(usize::from(padding))
95 .collect(),
96 )
97}
98
99/// The canonical form of a `BIGNUM` magnitude and sign: no leading zero byte,
100/// zero as the single byte `0` and never negative (`Bignum::Verify`).
101///
102/// # Errors
103///
104/// The magnitude, without its leading zeros, is longer than
105/// [`BIGNUM_MAX_BYTES`].
106pub(super) fn canonical_bignum(
107 magnitude_be: &[u8],
108 negative: bool,
109) -> Result<(Vec<u8>, bool), ExtensionError> {
110 let first = magnitude_be
111 .iter()
112 .position(|&b| b != 0)
113 .unwrap_or(magnitude_be.len());
114 let digits = magnitude_be.get(first..).unwrap_or_default();
115 if digits.is_empty() {
116 return Ok((vec![0], false));
117 }
118 if digits.len() > BIGNUM_MAX_BYTES {
119 return Err(ExtensionError::new(format!(
120 "Value::bignum: a magnitude of {} bytes exceeds DuckDB's BIGNUM maximum of \
121 {BIGNUM_MAX_BYTES} bytes",
122 digits.len()
123 )));
124 }
125 Ok((digits.to_vec(), negative))
126}
127
128impl Value {
129 /// Calls `read` with this value if it is a non-`NULL` value of type
130 /// `target`, or else with its [`try_cast`][Self::try_cast] to `target`.
131 /// `None` for a null handle, a SQL `NULL`, an unknown type, or a failed
132 /// cast. `read` therefore only ever sees a live, non-`NULL` handle whose
133 /// type is exactly `target`.
134 // Every path past the null-handle check calls DuckDB, so a `--lib` mutation run
135 // with no engine cannot reach it; covered end to end in tests/ffi_roundtrip.
136 #[cfg_attr(test, mutants::skip)]
137 fn with_type<R>(&self, target: TypeId, read: impl FnOnce(&Self) -> Option<R>) -> Option<R> {
138 if self.raw.is_null() || self.is_sql_null() {
139 return None;
140 }
141 if self.type_id()? == target {
142 return read(self);
143 }
144 let copy = self.try_cast(&LogicalType::try_new(target).ok()?)?;
145 if copy.is_sql_null() || copy.type_id() != Some(target) {
146 return None;
147 }
148 read(©)
149 }
150
151 /// The raw bytes of a non-`NULL` `BIT` value (padding byte, then data).
152 ///
153 /// Only call on a live, non-`NULL` value of type `BIT`.
154 // Every path past the null-handle check calls DuckDB, so a `--lib` mutation run
155 // with no engine cannot reach it; covered end to end in tests/ffi_roundtrip.
156 #[cfg_attr(test, mutants::skip)]
157 pub(super) fn bit_bytes(&self) -> Option<Vec<u8>> {
158 // SAFETY: the caller passes a live, non-NULL BIT value, so
159 // `DefaultCastAs(BIT)` is a copy and `StringValue::Get` does not throw;
160 // DuckDB `malloc`s the returned buffer (null only on allocation
161 // failure, from 2.0.0).
162 let bit: duckdb_bit = unsafe { duckdb_get_bit(self.raw) };
163 if bit.data.is_null() {
164 return None;
165 }
166 let len = usize::try_from(bit.size).ok();
167 // SAFETY: `bit.data` holds `bit.size` bytes, live until freed below.
168 let bytes = len.map(|len| unsafe { std::slice::from_raw_parts(bit.data, len) }.to_vec());
169 // SAFETY: `malloc`ed by `duckdb_get_bit`; `duckdb_free` is `free`.
170 unsafe { duckdb_free(bit.data.cast()) };
171 bytes
172 }
173
174 /// Creates a `BIT` value from its bits, leftmost first: `[false, true,
175 /// false, true]` is `'0101'::BIT`.
176 ///
177 /// # Errors
178 ///
179 /// `bits` is empty: SQL has no empty `BIT` (`''::BIT` is an error), and
180 /// `DuckDB` cannot render one.
181 ///
182 /// # Example
183 ///
184 /// ```rust,no_run
185 /// use quack_rs::value::Value;
186 ///
187 /// # fn demo() -> Result<(), quack_rs::error::ExtensionError> {
188 /// let flags = Value::bit(&[false, true, false, true])?;
189 /// assert_eq!(flags.as_str()?, "0101");
190 /// assert_eq!(flags.as_bit(), Some(vec![false, true, false, true]));
191 /// # Ok(())
192 /// # }
193 /// ```
194 pub fn bit(bits: &[bool]) -> Result<Self, ExtensionError> {
195 let bytes = encode_bits(bits)
196 .ok_or_else(|| ExtensionError::new("Value::bit: a BIT needs at least one bit"))?;
197 let size = idx_t::try_from(bytes.len())
198 .map_err(|_| ExtensionError::new("Value::bit: too many bits"))?;
199 // SAFETY: `bytes` is a well-formed BIT payload of `size` bytes, live
200 // for the call; `Value::BIT` copies it into a new owned value.
201 let raw = unsafe {
202 duckdb_create_bit(duckdb_bit {
203 data: bytes.as_ptr().cast_mut(),
204 size,
205 })
206 };
207 Self::checked(raw, "duckdb_create_bit")
208 }
209
210 /// Reads a `BIT` value as its bits, leftmost first.
211 ///
212 /// A value of another type is cast to `BIT` the way SQL's `TRY_CAST`
213 /// would (through [`try_cast`][Self::try_cast]): a `VARCHAR` `'0101'`
214 /// reads as four bits, an `INTEGER` as its 32 bits.
215 ///
216 /// Returns `None` for a null handle, a SQL `NULL`, a value that does not
217 /// cast to `BIT` (`'abc'`, a `DOUBLE`), and a `BIT` whose bytes are not
218 /// well formed. `duckdb_get_bit` itself aborts the process on the first
219 /// two and segfaults on a null handle; it is only ever called here on a
220 /// non-`NULL` `BIT` (see the module docs).
221 ///
222 /// Works on every supported `DuckDB` (1.4.4 to 2.0.x).
223 // Every path past the null-handle check calls DuckDB, so a `--lib` mutation run
224 // with no engine cannot reach it; covered end to end in tests/ffi_roundtrip.
225 #[cfg_attr(test, mutants::skip)]
226 #[must_use]
227 pub fn as_bit(&self) -> Option<Vec<bool>> {
228 self.with_type(TypeId::Bit, |bit| decode_bits(&bit.bit_bytes()?))
229 }
230
231 /// Creates a `BIGNUM` (arbitrary-precision integer) value from its
232 /// magnitude, most significant byte first, and its sign.
233 ///
234 /// Leading zero bytes are dropped, and zero (an empty or all-zero
235 /// magnitude) is stored as non-negative, which is the canonical form
236 /// `DuckDB` requires; `duckdb_create_bignum` would store either as given.
237 ///
238 /// # Errors
239 ///
240 /// The magnitude is longer than `DuckDB`'s maximum of 8,388,607 bytes.
241 ///
242 /// # Example
243 ///
244 /// ```rust,no_run
245 /// use quack_rs::value::Value;
246 ///
247 /// # fn demo() -> Result<(), quack_rs::error::ExtensionError> {
248 /// // -(2^64)
249 /// let big = Value::bignum(&[1, 0, 0, 0, 0, 0, 0, 0, 0], true)?;
250 /// assert_eq!(big.as_str()?, "-18446744073709551616");
251 /// assert_eq!(big.as_bignum(), Some((vec![1, 0, 0, 0, 0, 0, 0, 0, 0], true)));
252 /// # Ok(())
253 /// # }
254 /// ```
255 pub fn bignum(magnitude_be: &[u8], negative: bool) -> Result<Self, ExtensionError> {
256 let (mut digits, negative) = canonical_bignum(magnitude_be, negative)?;
257 let size = idx_t::try_from(digits.len())
258 .map_err(|_| ExtensionError::new("Value::bignum: magnitude too long"))?;
259 // SAFETY: `digits` is a canonical magnitude of `size` (>= 1) bytes,
260 // live for the call; `Bignum::FromByteArray` only reads it.
261 let raw = unsafe {
262 duckdb_create_bignum(duckdb_bignum {
263 data: digits.as_mut_ptr(),
264 size,
265 is_negative: negative,
266 })
267 };
268 Self::checked(raw, "duckdb_create_bignum")
269 }
270
271 /// Reads a `BIGNUM` value as its magnitude (most significant byte first,
272 /// no leading zero byte; zero is `[0]`) and whether it is negative.
273 ///
274 /// An integer or floating-point value is cast to `BIGNUM` the way SQL's
275 /// `TRY_CAST` would: a `BIGINT` `-5` reads as `([5], true)`.
276 ///
277 /// Returns `None` for a null handle, a SQL `NULL` and a value that does
278 /// not cast to `BIGNUM` (`'abc'`, a `BLOB`, an infinite `DOUBLE`), on
279 /// all of which `duckdb_get_bignum` itself aborts the process.
280 ///
281 /// A `BIGNUM` `DuckDB` builds is always well formed. One built through
282 /// the raw `duckdb_create_bignum` with an empty magnitude is not, and
283 /// reading it here — or rendering it with [`as_str`][Self::as_str] —
284 /// throws inside `DuckDB` and aborts; [`bignum`][Self::bignum] never
285 /// builds one.
286 ///
287 /// Works on every supported `DuckDB` (1.4.4 to 2.0.x).
288 // Every path past the null-handle check calls DuckDB, so a `--lib` mutation run
289 // with no engine cannot reach it; covered end to end in tests/ffi_roundtrip.
290 #[cfg_attr(test, mutants::skip)]
291 #[must_use]
292 pub fn as_bignum(&self) -> Option<(Vec<u8>, bool)> {
293 self.with_type(TypeId::Varint, |value| {
294 // SAFETY: `with_type` passes a live, non-NULL BIGNUM value, so
295 // `DefaultCastAs(BIGNUM)` is a copy and `StringValue::Get` does
296 // not throw; DuckDB `malloc`s the returned magnitude.
297 let raw: duckdb_bignum = unsafe { duckdb_get_bignum(value.raw) };
298 if raw.data.is_null() {
299 return None;
300 }
301 let len = usize::try_from(raw.size).ok();
302 // SAFETY: `raw.data` holds `raw.size` bytes until freed below.
303 let digits =
304 len.map(|len| unsafe { std::slice::from_raw_parts(raw.data, len) }.to_vec());
305 // SAFETY: `malloc`ed by `duckdb_get_bignum`; `duckdb_free` is `free`.
306 unsafe { duckdb_free(raw.data.cast()) };
307 Some((digits?, raw.is_negative))
308 })
309 }
310}
311
312#[cfg(test)]
313mod tests {
314 use super::*;
315
316 #[test]
317 fn bits_encode_right_aligned_with_padding_set() {
318 assert_eq!(encode_bits(&[]), None);
319 // '0101': 4 padding bits (set), then 0101.
320 assert_eq!(
321 encode_bits(&[false, true, false, true]),
322 Some(vec![4, 0b1111_0101])
323 );
324 // Exactly one byte: no padding.
325 assert_eq!(encode_bits(&[true; 8]), Some(vec![0, 0xff]));
326 assert_eq!(encode_bits(&[false; 8]), Some(vec![0, 0x00]));
327 // Nine bits: 7 padding bits in the first byte.
328 let nine = [true, false, false, false, false, false, false, false, true];
329 assert_eq!(encode_bits(&nine), Some(vec![7, 0b1111_1111, 0b0000_0001]));
330 assert_eq!(encode_bits(&[false]), Some(vec![7, 0b1111_1110]));
331 }
332
333 #[test]
334 fn bits_decode_what_they_encode() {
335 for len in 1_usize..=40 {
336 let bits: Vec<bool> = (0..len).map(|i| (i * 7 + len) % 3 == 0).collect();
337 let bytes = encode_bits(&bits).expect("non-empty");
338 assert_eq!(bytes.len(), 1 + len.div_ceil(8), "len {len}");
339 assert_eq!(decode_bits(&bytes), Some(bits), "len {len}");
340 }
341 }
342
343 #[test]
344 fn malformed_bit_bytes_decode_to_none() {
345 assert_eq!(decode_bits(&[]), None, "no padding byte");
346 assert_eq!(decode_bits(&[0]), None, "padding byte only");
347 assert_eq!(decode_bits(&[8, 0xff]), None, "padding above 7");
348 assert_eq!(decode_bits(&[9, 0xff]), None, "padding above 7");
349 // The padding bits' values are ignored.
350 assert_eq!(
351 decode_bits(&[4, 0b0000_0101]),
352 Some(vec![false, true, false, true])
353 );
354 assert_eq!(decode_bits(&[7, 0x01]), Some(vec![true]));
355 }
356
357 #[test]
358 fn bignum_magnitudes_are_canonicalised() {
359 assert_eq!(canonical_bignum(&[], false).ok(), Some((vec![0], false)));
360 assert_eq!(canonical_bignum(&[], true).ok(), Some((vec![0], false)));
361 assert_eq!(canonical_bignum(&[0, 0], true).ok(), Some((vec![0], false)));
362 assert_eq!(
363 canonical_bignum(&[0, 0, 5], true).ok(),
364 Some((vec![5], true))
365 );
366 assert_eq!(
367 canonical_bignum(&[1, 0], false).ok(),
368 Some((vec![1, 0], false))
369 );
370 assert_eq!(
371 canonical_bignum(&[0, 1, 0], true).ok(),
372 Some((vec![1, 0], true))
373 );
374 }
375
376 #[test]
377 fn a_bignum_longer_than_duckdb_stores_is_refused() {
378 let mut max = vec![0_u8; BIGNUM_MAX_BYTES];
379 max[0] = 1;
380 assert!(canonical_bignum(&max, false).is_ok());
381 max.push(0);
382 let err = canonical_bignum(&max, false).expect_err("one byte too long");
383 assert!(err.as_str().contains("8388607"), "{err}");
384 // Leading zeros do not count against the limit.
385 let mut padded = vec![0_u8; 4];
386 padded.extend_from_slice(&[1; 16]);
387 assert_eq!(
388 canonical_bignum(&padded, true).ok(),
389 Some((vec![1; 16], true))
390 );
391 }
392
393 #[test]
394 fn getters_on_a_null_handle_do_not_call_duckdb() {
395 // SAFETY: a null handle is part of `Value`'s contract.
396 let value = unsafe { Value::from_raw(std::ptr::null_mut()) };
397 assert_eq!(value.as_bit(), None);
398 assert_eq!(value.as_bignum(), None);
399 }
400}