quack_rs/vector/string.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//! `DuckDB` `VARCHAR` and `BLOB` (`duckdb_string_t`) reading utilities.
7//!
8//! # Pitfall P7: Undocumented `duckdb_string_t` format
9//!
10//! `DuckDB` stores VARCHAR values in a 16-byte `duckdb_string_t` struct with two
11//! representations:
12//!
13//! - **Inline** (length ≤ 12): `[ len: u32 | data: [u8; 12] ]`
14//! - **Pointer** (length > 12): `[ len: u32 | prefix: [u8; 4] | ptr: *const u8 ]`, the
15//! pointer at offset 8 (on a 32-bit target it takes 4 bytes and 4 bytes of
16//! padding follow)
17//!
18//! This is not documented in the Rust bindings. The layout was determined by
19//! reading `DuckDB`'s C source and confirmed by the duckdb-behavioral implementation.
20//!
21//! # Example
22//!
23//! ```rust
24//! use quack_rs::vector::string::{DuckStringView, read_duck_string};
25//!
26//! // A short string (inline case)
27//! let bytes: [u8; 16] = {
28//! let mut b = [0u8; 16];
29//! b[0] = 5; // length = 5
30//! b[4..9].copy_from_slice(b"hello");
31//! b
32//! };
33//! let view = DuckStringView::inline_from_bytes(&bytes).expect("inline value");
34//! assert_eq!(view.as_str(), Some("hello"));
35//! assert_eq!(view.len(), 5);
36//! ```
37
38/// The size of a `duckdb_string_t` in bytes.
39pub const DUCK_STRING_SIZE: usize = 16;
40
41/// The maximum string length that fits inline in a `duckdb_string_t` (≤12 bytes).
42pub const DUCK_STRING_INLINE_MAX_LEN: usize = 12;
43
44/// The longest `VARCHAR` or `BLOB` value `DuckDB` can store, in bytes:
45/// `string_t::MAX_STRING_SIZE`, which is `u32::MAX` because the length field
46/// of a `duckdb_string_t` is a `u32`.
47///
48/// `DuckDB` does not enforce it when a value is written through the C API:
49/// `StringVector::AddStringOrBlob` narrows the 64-bit length with a plain cast
50/// in release builds, so a longer value is stored as its length modulo 2^32 —
51/// truncated, and for a `VARCHAR` possibly cut inside a UTF-8 sequence.
52/// [`VectorWriter::write_varchar`][crate::vector::VectorWriter::write_varchar]
53/// and its siblings check this limit first.
54#[allow(
55 clippy::cast_possible_truncation,
56 reason = "u32 -> usize is lossless on every target with at least 32-bit pointers, which is all Rust targets DuckDB supports"
57)]
58pub const MAX_STRING_LEN: usize = u32::MAX as usize;
59
60/// Returns an error if `len` exceeds [`MAX_STRING_LEN`].
61///
62/// # Errors
63///
64/// Returns an error naming both lengths when `len > MAX_STRING_LEN`.
65pub fn check_string_len(len: usize) -> Result<(), crate::error::ExtensionError> {
66 if len > MAX_STRING_LEN {
67 return Err(crate::error::ExtensionError::new(format!(
68 "value of {len} bytes exceeds DuckDB's maximum string length of {MAX_STRING_LEN} bytes"
69 )));
70 }
71 Ok(())
72}
73
74/// A parsed view of a `duckdb_string_t` value.
75///
76/// This type borrows from the raw vector data — it does not allocate.
77///
78/// # Constructing a view
79///
80/// A `duckdb_string_t` longer than [`DUCK_STRING_INLINE_MAX_LEN`] stores a raw
81/// heap pointer in bytes 8–15. Reading such a value means dereferencing a
82/// pointer taken from the input bytes, which can only be justified by the
83/// caller — so it lives behind [`from_raw`][Self::from_raw], an `unsafe fn`.
84///
85/// [`inline_from_bytes`][Self::inline_from_bytes] is the safe constructor: it
86/// accepts any 16 bytes and refuses (returns `None`) whenever the value is in
87/// pointer format, so a view built through it can never dereference anything.
88#[derive(Debug, Clone, Copy)]
89pub struct DuckStringView<'a> {
90 bytes: &'a [u8],
91 length: usize,
92 /// `true` when the caller has vouched for the pointer in bytes 8–15 by going
93 /// through the `unsafe` constructor. Views built safely keep this `false`
94 /// and never dereference.
95 pointer_is_trusted: bool,
96}
97
98impl<'a> DuckStringView<'a> {
99 /// Creates a `DuckStringView` from a genuine `duckdb_string_t`.
100 ///
101 /// This is the constructor to use inside `DuckDB` callbacks, where the 16
102 /// bytes really did come from a `DuckDB` vector.
103 ///
104 /// # Safety
105 ///
106 /// If the length field (bytes 0–3) exceeds [`DUCK_STRING_INLINE_MAX_LEN`],
107 /// bytes 8–15 must hold a valid pointer to at least `length` readable bytes
108 /// that stay live for `'a`.
109 #[must_use]
110 pub const unsafe fn from_raw(raw: &'a [u8; DUCK_STRING_SIZE]) -> Self {
111 let length = u32::from_ne_bytes([raw[0], raw[1], raw[2], raw[3]]) as usize;
112 Self {
113 bytes: raw,
114 length,
115 pointer_is_trusted: true,
116 }
117 }
118
119 /// Creates a `DuckStringView` from 16 bytes that may come from anywhere.
120 ///
121 /// Returns `None` if the value is in pointer format (length >
122 /// [`DUCK_STRING_INLINE_MAX_LEN`]), because honouring the embedded pointer
123 /// would mean dereferencing an address chosen by the input.
124 ///
125 /// # Example
126 ///
127 /// ```rust
128 /// use quack_rs::vector::string::DuckStringView;
129 ///
130 /// let mut inline = [0u8; 16];
131 /// inline[..4].copy_from_slice(&5u32.to_ne_bytes());
132 /// inline[4..9].copy_from_slice(b"hello");
133 /// assert_eq!(
134 /// DuckStringView::inline_from_bytes(&inline).and_then(|v| v.as_str()),
135 /// Some("hello")
136 /// );
137 ///
138 /// // A pointer-format value is refused rather than dereferenced.
139 /// let mut pointer_format = [0u8; 16];
140 /// pointer_format[..4].copy_from_slice(&64u32.to_ne_bytes());
141 /// pointer_format[8..16].copy_from_slice(&0xdead_beef_u64.to_ne_bytes());
142 /// assert!(DuckStringView::inline_from_bytes(&pointer_format).is_none());
143 /// ```
144 #[must_use]
145 pub const fn inline_from_bytes(raw: &'a [u8; DUCK_STRING_SIZE]) -> Option<Self> {
146 let length = u32::from_ne_bytes([raw[0], raw[1], raw[2], raw[3]]) as usize;
147 if length > DUCK_STRING_INLINE_MAX_LEN {
148 return None;
149 }
150 Some(Self {
151 bytes: raw,
152 length,
153 pointer_is_trusted: false,
154 })
155 }
156
157 /// Creates a `DuckStringView` from the raw 16-byte representation.
158 ///
159 /// # Deprecated
160 ///
161 /// This constructor is safe but cannot honour pointer-format values: doing
162 /// so would dereference an address supplied by its (safe) caller. It now
163 /// behaves exactly like [`inline_from_bytes`][Self::inline_from_bytes]
164 /// except that it cannot report the refusal, so a pointer-format value
165 /// yields a view whose accessors return `None`.
166 ///
167 /// Use [`from_raw`][Self::from_raw] for real `duckdb_string_t` values, or
168 /// [`inline_from_bytes`][Self::inline_from_bytes] when the input is
169 /// untrusted and you want the refusal to be visible.
170 #[must_use]
171 #[deprecated(
172 since = "0.16.0",
173 note = "use `DuckStringView::from_raw` (unsafe, honours pointer format) or \
174 `DuckStringView::inline_from_bytes` (safe, refuses pointer format)"
175 )]
176 pub const fn from_bytes(raw: &'a [u8; DUCK_STRING_SIZE]) -> Self {
177 let length = u32::from_ne_bytes([raw[0], raw[1], raw[2], raw[3]]) as usize;
178 Self {
179 bytes: raw,
180 length,
181 pointer_is_trusted: false,
182 }
183 }
184
185 /// Returns the length of the string in bytes.
186 #[must_use]
187 #[inline]
188 pub const fn len(&self) -> usize {
189 self.length
190 }
191
192 /// Returns `true` if the string is empty.
193 #[must_use]
194 #[inline]
195 pub const fn is_empty(&self) -> bool {
196 self.length == 0
197 }
198
199 /// Returns the string as a UTF-8 `str` slice, or `None` if it is not valid UTF-8.
200 ///
201 /// The returned `&'a str` has the same lifetime as the underlying data slice —
202 /// not the lifetime of `self`. This allows the result to outlive the `DuckStringView`.
203 ///
204 /// Returns `None` when the bytes are not valid UTF-8, when a pointer-format
205 /// value carries a null pointer, or when this view was built through a safe
206 /// constructor and the value is in pointer format (see
207 /// [`inline_from_bytes`][Self::inline_from_bytes]).
208 ///
209 /// The pointer-format obligation — that bytes 8–15 address `len()` live
210 /// bytes — was discharged when the view was created via
211 /// [`from_raw`][Self::from_raw].
212 #[must_use]
213 pub fn as_str(&self) -> Option<&'a str> {
214 let slice = self.as_bytes_unsafe()?;
215 // Nearly every column is ASCII, and `is_ascii` is several times faster
216 // than `from_utf8` on the short strings DuckDB stores inline.
217 if slice.is_ascii() {
218 // SAFETY: ASCII bytes are valid UTF-8.
219 return Some(unsafe { std::str::from_utf8_unchecked(slice) });
220 }
221 std::str::from_utf8(slice).ok()
222 }
223
224 /// Returns the raw bytes of the string content.
225 ///
226 /// Returns `None` if the internal pointer (for long strings) is null.
227 ///
228 /// The returned bytes have lifetime `'a` (the lifetime of the underlying data).
229 ///
230 /// # Platform assumption
231 ///
232 /// The length (bytes 0–3) and the pointer (from byte 8) are read in the
233 /// target's byte order, as `DuckDB` writes them. The pointer is read at the
234 /// target's pointer width: 8 bytes on 64-bit targets; 4 on 32-bit
235 /// (DuckDB-WASM via `wasm32-unknown-emscripten`), where the C union still
236 /// spans 16 bytes but bytes 12–15 are **not** guaranteed to be zero:
237 /// `DuckDB`'s `string_t` constructor writes only the length, prefix and
238 /// 4-byte pointer for a long string, so those bytes keep whatever the slot
239 /// held before (e.g. the tail of an earlier inlined string), and are not
240 /// read.
241 ///
242 /// # Safety (internal)
243 ///
244 /// This method dereferences the pointer stored in the `duckdb_string_t` struct
245 /// for strings longer than 12 bytes. The caller (i.e., the `DuckStringView`
246 /// constructor) must ensure the underlying vector data is still valid.
247 fn as_bytes_unsafe(&self) -> Option<&'a [u8]> {
248 if self.length <= DUCK_STRING_INLINE_MAX_LEN {
249 // Inline case: data starts at byte 4, length bytes follow
250 Some(&self.bytes[4..4 + self.length])
251 } else if !self.pointer_is_trusted {
252 // Pointer format, but this view was built through a safe
253 // constructor. Dereferencing bytes 8..16 would follow an address the
254 // safe caller supplied, so refuse instead.
255 None
256 } else {
257 // Pointer case: `duckdb_string_t`'s `char *ptr` sits at offset 8 on
258 // every target (after the `uint32_t` length and the 4-byte prefix),
259 // in the target's own byte order and width. Reading it as a pointer
260 // takes exactly those bytes — 8 on 64-bit, 4 on wasm32, where the
261 // rest of the slot may hold stale bytes DuckDB does not clear — and
262 // keeps the address's provenance.
263 let slot = self.bytes.get(8..8 + std::mem::size_of::<*const u8>())?;
264 // SAFETY: `slot` is `size_of::<*const u8>()` in-bounds bytes of
265 // `self.bytes`; `read_unaligned` needs no alignment, and any bit
266 // pattern is a valid raw pointer.
267 let ptr_val = unsafe { slot.as_ptr().cast::<*const u8>().read_unaligned() };
268 if ptr_val.is_null() {
269 return None;
270 }
271 // SAFETY: `ptr_val` is a DuckDB-managed pointer; the caller guarantees
272 // the underlying data is valid for the lifetime of the DuckStringView.
273 Some(unsafe { std::slice::from_raw_parts(ptr_val, self.length) })
274 }
275 }
276}
277
278/// Reads a `DuckDB` `VARCHAR` value from a raw vector data pointer at a given row index.
279///
280/// Returns the string as a `&str` slice, or an empty string if the data is not
281/// valid UTF-8 or if the pointer is null.
282///
283/// # Pitfall P7
284///
285/// `DuckDB` strings have two storage formats:
286/// - **Inline** (≤ 12 bytes): stored directly in the 16-byte struct
287/// - **Pointer** (> 12 bytes): struct contains a pointer to heap-allocated data
288///
289/// This function handles both transparently.
290///
291/// # Safety
292///
293/// - `data` must point to a `DuckDB` VARCHAR vector's data buffer.
294/// - `idx` must be within bounds of the vector.
295/// - For pointer-format strings, the heap data pointed to must be valid for the
296/// duration of this function call and the returned `&str` slice. A NULL row
297/// cannot promise that — `DuckDB` leaves a NULL row's payload as it was,
298/// which can be a pointer from an earlier chunk — so do not read NULL rows.
299/// - The returned `&str` borrows from the `DuckDB` vector — do not destroy the
300/// data chunk while the returned reference is live.
301///
302/// # Example
303///
304/// ```rust,no_run
305/// use quack_rs::vector::string::read_duck_string;
306///
307/// // Inside a DuckDB aggregate callback:
308/// // let data = libduckdb_sys::duckdb_vector_get_data(vec) as *const u8;
309/// // let s = unsafe { read_duck_string(data, row_idx) };
310/// # let data: *const u8 = std::ptr::null();
311/// # let _ = data;
312/// ```
313pub unsafe fn read_duck_string<'a>(data: *const u8, idx: usize) -> &'a str {
314 // SAFETY: Each duckdb_string_t is exactly 16 bytes. The caller guarantees
315 // `data` is valid and `idx` is in bounds.
316 let str_ptr = unsafe { data.add(idx * DUCK_STRING_SIZE) };
317 // SAFETY: `str_ptr` points to the idx-th duckdb_string_t in the vector.
318 // The reference has lifetime 'a because it borrows from the raw pointer
319 // whose backing data lives for the vector's lifetime ('a per caller's contract).
320 let raw_bytes: &'a [u8; DUCK_STRING_SIZE] =
321 unsafe { &*str_ptr.cast::<[u8; DUCK_STRING_SIZE]>() };
322 // DuckStringView<'a> stores &'a [u8], so as_str() returns Option<&'a str>.
323 // SAFETY: the caller vouched for the vector's pointer-format payloads.
324 unsafe { DuckStringView::from_raw(raw_bytes) }
325 .as_str()
326 .unwrap_or("")
327}
328
329/// Reads a `DuckDB` `BLOB` value at the given row index.
330///
331/// Returns the raw bytes without UTF-8 validation, or an empty slice if a
332/// pointer-format value contains a null pointer. `BLOB` and `VARCHAR` share the
333/// same `duckdb_string_t` layout (inline for ≤ 12 bytes, pointer otherwise).
334///
335/// # Safety
336///
337/// - `data` must point at a `DuckDB` BLOB (or VARCHAR) vector's data buffer.
338/// - `idx` must be within bounds of the vector.
339/// - For pointer-format blobs, the heap data must be valid for the lifetime of
340/// the returned slice. A NULL row cannot promise that — `DuckDB` leaves a
341/// NULL row's payload as it was, which can be a pointer from an earlier
342/// chunk — so do not read NULL rows.
343/// - The returned slice can borrow from the vector's own data buffer (an inline
344/// blob of 12 bytes or fewer is stored there), so the vector must also
345/// outlive it — do not destroy the data chunk while the slice is live.
346pub unsafe fn read_duck_blob<'a>(data: *const u8, idx: usize) -> &'a [u8] {
347 // SAFETY: each duckdb_string_t is exactly DUCK_STRING_SIZE bytes.
348 let str_ptr = unsafe { data.add(idx * DUCK_STRING_SIZE) };
349 // SAFETY: `[u8; 16]` has alignment 1, and `str_ptr` points at row `idx`'s
350 // 16-byte `duckdb_string_t` inside the vector's data buffer (`# Safety`
351 // clauses 1-2), so the bytes are in bounds; clause 4 keeps the vector, and
352 // so this record, alive for the caller-chosen `'a`.
353 let raw_bytes: &'a [u8; DUCK_STRING_SIZE] =
354 unsafe { &*str_ptr.cast::<[u8; DUCK_STRING_SIZE]>() };
355 // SAFETY: the caller vouched for the vector's pointer-format payloads.
356 unsafe { DuckStringView::from_raw(raw_bytes) }
357 .as_bytes_unsafe()
358 .unwrap_or(&[])
359}
360
361#[cfg(test)]
362mod tests {
363 #[test]
364 fn string_length_limit_is_duckdbs_u32_length_field() {
365 assert_eq!(super::MAX_STRING_LEN as u64, u64::from(u32::MAX));
366 assert!(super::check_string_len(0).is_ok());
367 assert!(super::check_string_len(super::MAX_STRING_LEN).is_ok());
368 #[cfg(target_pointer_width = "64")]
369 {
370 let err = super::check_string_len(super::MAX_STRING_LEN + 1).expect_err("too long");
371 assert!(err.as_str().contains("4294967296 bytes"), "{err}");
372 }
373 }
374
375 use super::*;
376
377 /// Stores `ptr` at byte 8 the way `DuckDB`'s `char *ptr` field holds it:
378 /// native byte order, pointer width, provenance kept.
379 fn put_pointer(bytes: &mut [u8; 16], ptr: *const u8) {
380 // SAFETY: bytes 8..16 hold the `size_of::<*const u8>()` (at most 8)
381 // bytes written; `write_unaligned` needs no alignment.
382 unsafe {
383 bytes[8..]
384 .as_mut_ptr()
385 .cast::<*const u8>()
386 .write_unaligned(ptr);
387 }
388 }
389
390 fn make_inline_bytes(s: &str) -> [u8; 16] {
391 assert!(
392 s.len() <= DUCK_STRING_INLINE_MAX_LEN,
393 "use pointer format for long strings"
394 );
395 let mut bytes = [0u8; 16];
396 let len = u32::try_from(s.len()).unwrap_or(u32::MAX);
397 bytes[..4].copy_from_slice(&len.to_ne_bytes());
398 bytes[4..4 + s.len()].copy_from_slice(s.as_bytes());
399 bytes
400 }
401
402 #[test]
403 fn empty_string_inline() {
404 let bytes = make_inline_bytes("");
405 let view = DuckStringView::inline_from_bytes(&bytes).expect("inline");
406 assert_eq!(view.len(), 0);
407 assert!(view.is_empty());
408 assert_eq!(view.as_str(), Some(""));
409 }
410
411 #[test]
412 fn short_string_inline() {
413 let bytes = make_inline_bytes("hello");
414 let view = DuckStringView::inline_from_bytes(&bytes).expect("inline");
415 assert_eq!(view.len(), 5);
416 assert!(!view.is_empty());
417 assert_eq!(view.as_str(), Some("hello"));
418 }
419
420 #[test]
421 fn max_inline_string() {
422 let s = "abcdefghijkl"; // exactly 12 bytes
423 assert_eq!(s.len(), DUCK_STRING_INLINE_MAX_LEN);
424 let bytes = make_inline_bytes(s);
425 let view = DuckStringView::inline_from_bytes(&bytes).expect("inline");
426 assert_eq!(view.len(), 12);
427 assert_eq!(view.as_str(), Some(s));
428 }
429
430 #[test]
431 fn read_duck_blob_preserves_non_utf8_inline_bytes() {
432 let payload = [0x80u8, 0xF0, 0x01, 0x42];
433 let mut bytes = [0u8; 16];
434 let len = u32::try_from(payload.len()).unwrap_or(u32::MAX);
435 bytes[..4].copy_from_slice(&len.to_ne_bytes());
436 bytes[4..4 + payload.len()].copy_from_slice(&payload);
437
438 assert_eq!(unsafe { read_duck_blob(bytes.as_ptr(), 0) }, &payload);
439 assert_eq!(unsafe { read_duck_string(bytes.as_ptr(), 0) }, "");
440 }
441
442 #[test]
443 fn read_duck_blob_preserves_non_utf8_pointer_bytes() {
444 let payload = [
445 0x80u8, 0xF0, 0x01, 0x42, 0xFF, 0x00, 0xFE, 0x7F, 0xAA, 0x55, 0xC0, 0xAF, 0x90,
446 ];
447 let mut bytes = [0u8; 16];
448 let len = u32::try_from(payload.len()).unwrap_or(u32::MAX);
449 bytes[..4].copy_from_slice(&len.to_ne_bytes());
450 bytes[4..8].copy_from_slice(&payload[..4]);
451 put_pointer(&mut bytes, payload.as_ptr());
452
453 assert_eq!(unsafe { read_duck_blob(bytes.as_ptr(), 0) }, &payload);
454 }
455
456 #[test]
457 fn pointer_format_string() {
458 let long_str = "this is a longer string that exceeds 12 bytes";
459 let len = long_str.len();
460 let ptr = long_str.as_ptr();
461
462 let mut bytes = [0u8; 16];
463 // Write length
464 bytes[..4].copy_from_slice(&u32::try_from(len).unwrap_or(u32::MAX).to_ne_bytes());
465 // Write prefix (first 4 bytes of the string)
466 bytes[4..8].copy_from_slice(&long_str.as_bytes()[..4]);
467 // Write the pointer at byte 8, as DuckDB does
468 put_pointer(&mut bytes, ptr);
469
470 // SAFETY: `bytes` really does point at `long_str`, which outlives the view.
471 let view = unsafe { DuckStringView::from_raw(&bytes) };
472 assert_eq!(view.len(), len);
473 assert_eq!(view.as_str(), Some(long_str));
474 }
475
476 #[test]
477 fn pointer_null_returns_none() {
478 let mut bytes = [0u8; 16];
479 // Write length > 12
480 bytes[..4].copy_from_slice(&13u32.to_ne_bytes());
481 // pointer bytes 8..16 remain 0 (null pointer)
482
483 // SAFETY: the length says pointer-format, and the null pointer case is
484 // exactly what this test exercises.
485 let view = unsafe { DuckStringView::from_raw(&bytes) };
486 // Null pointer for long string should return None
487 assert!(view.as_str().is_none());
488 assert_eq!(unsafe { read_duck_blob(bytes.as_ptr(), 0) }, [] as [u8; 0]);
489 }
490
491 #[test]
492 fn read_duck_string_inline() {
493 let bytes = make_inline_bytes("world");
494 let data = bytes.as_ptr();
495 // SAFETY: data points to a valid 16-byte inline string at idx 0.
496 let s = unsafe { read_duck_string(data, 0) };
497 assert_eq!(s, "world");
498 }
499
500 #[test]
501 fn read_duck_string_pointer_format() {
502 let long_str = "abcdefghijklmnopqrst"; // 20 bytes
503 let len = long_str.len();
504 let ptr = long_str.as_ptr();
505
506 let mut bytes = [0u8; 16];
507 bytes[..4].copy_from_slice(&u32::try_from(len).unwrap_or(u32::MAX).to_ne_bytes());
508 bytes[4..8].copy_from_slice(&long_str.as_bytes()[..4]);
509 put_pointer(&mut bytes, ptr);
510
511 // SAFETY: bytes is a valid pointer-format duckdb_string_t at idx 0.
512 let s = unsafe { read_duck_string(bytes.as_ptr(), 0) };
513 assert_eq!(s, long_str);
514 }
515
516 #[test]
517 fn safe_constructor_refuses_pointer_format_instead_of_dereferencing() {
518 // A hostile 16 bytes: length says "pointer format", and the pointer slot
519 // holds an address that must never be dereferenced.
520 let mut bytes = [0u8; DUCK_STRING_SIZE];
521 bytes[..4].copy_from_slice(&1024u32.to_ne_bytes());
522 bytes[8..16].copy_from_slice(&0xdead_beef_dead_beef_u64.to_ne_bytes());
523
524 assert!(DuckStringView::inline_from_bytes(&bytes).is_none());
525 }
526
527 /// `as_str` takes an ASCII fast path and falls back to full validation:
528 /// both must agree with `std::str::from_utf8` on every inline length, with
529 /// multi-byte text and with an invalid byte in any position.
530 #[test]
531 fn as_str_agrees_with_from_utf8_on_ascii_multibyte_and_invalid_bytes() {
532 let mut cases: Vec<Vec<u8>> = vec![
533 b"plain ascii".to_vec(),
534 "caf\u{e9}".as_bytes().to_vec(),
535 "\u{65e5}\u{672c}\u{8a9e}".as_bytes().to_vec(),
536 "\u{1f986}".as_bytes().to_vec(),
537 ];
538 // One high-bit byte at each position of a 12-byte inline string, valid
539 // only as the continuation of the pair it starts or ends.
540 for at in 0..DUCK_STRING_INLINE_MAX_LEN {
541 for byte in [0x80_u8, 0xC3, 0xFF] {
542 let mut raw = *b"abcdefghijkl";
543 raw[at] = byte;
544 cases.push(raw.to_vec());
545 }
546 }
547 for case in cases {
548 let mut bytes = [0u8; DUCK_STRING_SIZE];
549 let len = u32::try_from(case.len()).expect("fits");
550 bytes[..4].copy_from_slice(&len.to_ne_bytes());
551 bytes[4..4 + case.len()].copy_from_slice(&case);
552 let view = DuckStringView::inline_from_bytes(&bytes).expect("inline");
553 assert_eq!(view.as_str(), std::str::from_utf8(&case).ok(), "{case:?}");
554 }
555 }
556
557 #[test]
558 fn safe_constructor_accepts_every_inline_length() {
559 for len in 0..=DUCK_STRING_INLINE_MAX_LEN {
560 let mut bytes = [b'x'; DUCK_STRING_SIZE];
561 bytes[..4].copy_from_slice(&u32::try_from(len).expect("fits").to_ne_bytes());
562 let view = DuckStringView::inline_from_bytes(&bytes)
563 .unwrap_or_else(|| panic!("length {len} must be inline"));
564 assert_eq!(view.len(), len);
565 assert_eq!(view.as_str().map(str::len), Some(len));
566 }
567 }
568
569 #[test]
570 #[allow(deprecated)]
571 fn deprecated_constructor_no_longer_dereferences() {
572 // The old safe `from_bytes` used to follow this pointer. It must not.
573 let mut bytes = [0u8; DUCK_STRING_SIZE];
574 bytes[..4].copy_from_slice(&64u32.to_ne_bytes());
575 bytes[8..16].copy_from_slice(&0xdead_beef_dead_beef_u64.to_ne_bytes());
576
577 let view = DuckStringView::from_bytes(&bytes);
578 assert_eq!(view.len(), 64);
579 assert_eq!(view.as_str(), None);
580 }
581
582 /// A `duckdb_string_t` filled through its own C fields, as `DuckDB` fills
583 /// it: the length and the pointer in the target's byte order. Decoding
584 /// assumed little-endian, so on a big-endian target an inline string's
585 /// length read as `len << 24` and the decoder followed its inlined bytes
586 /// as a pointer. Run under Miri with `--target s390x-unknown-linux-gnu`
587 /// to exercise the big-endian case.
588 #[test]
589 fn a_duckdb_string_t_in_native_layout_is_decoded() {
590 use libduckdb_sys::{
591 duckdb_string_t, duckdb_string_t__bindgen_ty_1,
592 duckdb_string_t__bindgen_ty_1__bindgen_ty_1 as Pointer,
593 duckdb_string_t__bindgen_ty_1__bindgen_ty_2 as Inlined,
594 };
595 let short = "hello";
596 let mut inlined = [0 as std::os::raw::c_char; 12];
597 for (dst, &b) in inlined.iter_mut().zip(short.as_bytes()) {
598 *dst = std::os::raw::c_char::from_ne_bytes([b]);
599 }
600 let long = "a string longer than twelve bytes";
601 let mut prefix = [0 as std::os::raw::c_char; 4];
602 for (dst, &b) in prefix.iter_mut().zip(long.as_bytes()) {
603 *dst = std::os::raw::c_char::from_ne_bytes([b]);
604 }
605 let rows = [
606 duckdb_string_t {
607 value: duckdb_string_t__bindgen_ty_1 {
608 inlined: Inlined { length: 5, inlined },
609 },
610 },
611 duckdb_string_t {
612 value: duckdb_string_t__bindgen_ty_1 {
613 pointer: Pointer {
614 length: u32::try_from(long.len()).expect("short"),
615 prefix,
616 ptr: long.as_ptr().cast_mut().cast(),
617 },
618 },
619 },
620 ];
621 assert_eq!(std::mem::size_of_val(&rows), 2 * DUCK_STRING_SIZE);
622 let data = rows.as_ptr().cast::<u8>();
623 // SAFETY: `data` is two genuine `duckdb_string_t` rows; the second
624 // points at `long`, which outlives both reads.
625 assert_eq!(unsafe { read_duck_string(data, 0) }, short);
626 assert_eq!(unsafe { read_duck_string(data, 1) }, long);
627 assert_eq!(unsafe { read_duck_blob(data, 1) }, long.as_bytes());
628 }
629
630 #[test]
631 fn duck_string_size_constant() {
632 assert_eq!(DUCK_STRING_SIZE, 16);
633 }
634
635 #[test]
636 fn duck_string_inline_max_len_constant() {
637 assert_eq!(DUCK_STRING_INLINE_MAX_LEN, 12);
638 }
639}