Skip to main content

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}