libduckdb_sys/
string.rs

1use std::{
2    ffi::{CStr, c_char},
3    ops::Deref,
4};
5
6use crate::duckdb_free;
7
8pub struct DuckDbString {
9    // Invariant: ptr[0..len+1] is valid C string, i.e. ptr[len] is NUL byte.
10    ptr: core::ptr::NonNull<c_char>,
11    len: usize,
12}
13
14impl DuckDbString {
15    /// Creates a `DuckDbString` from a raw pointer to a C string.
16    ///
17    /// # Safety
18    ///
19    /// The caller must ensure that:
20    /// - `ptr` is non-null and points to a null-terminated C string.
21    /// - `ptr` was allocated by DuckDB and must be released with `duckdb_free`.
22    /// - Ownership of `ptr` transfers to the returned `DuckDbString`. The caller must not reuse or free it.
23    pub unsafe fn from_ptr(ptr: *const c_char) -> Self {
24        assert!(!ptr.is_null(), "DuckDbString::from_ptr requires a non-null pointer");
25        let len = unsafe { CStr::from_ptr(ptr) }.to_bytes().len();
26        unsafe { Self::from_raw_parts(ptr, len) }
27    }
28
29    /// Creates a `DuckDbString` from a nullable raw pointer to a C string.
30    ///
31    /// Returns `None` if `ptr` is null.
32    ///
33    /// # Safety
34    ///
35    /// If `ptr` is non-null, the caller must ensure that:
36    /// - `ptr` points to a null-terminated C string.
37    /// - `ptr` was allocated by DuckDB and must be released with `duckdb_free`.
38    /// - Ownership of `ptr` transfers to the returned `DuckDbString`. The caller must not reuse or free it.
39    pub unsafe fn from_nullable_ptr(ptr: *const c_char) -> Option<Self> {
40        if ptr.is_null() {
41            None
42        } else {
43            Some(unsafe { Self::from_ptr(ptr) })
44        }
45    }
46
47    /// Creates a `DuckDbString` from raw parts.
48    ///
49    /// # Safety
50    ///
51    /// The caller must ensure that:
52    /// - `ptr` is non-null and points to a null-terminated C string.
53    /// - `len` accurately represents the length of the string (excluding the null terminator).
54    /// - `ptr` was allocated by DuckDB and must be released with `duckdb_free`.
55    /// - Ownership of `ptr` transfers to the returned `DuckDbString`. The caller must not reuse or free it.
56    /// - The string data is not mutated for the lifetime of the returned `DuckDbString`.
57    pub unsafe fn from_raw_parts(ptr: *const c_char, len: usize) -> Self {
58        let ptr = core::ptr::NonNull::new(ptr as *mut c_char)
59            .expect("DuckDbString::from_raw_parts requires a non-null pointer");
60        Self { ptr, len }
61    }
62
63    fn to_bytes_with_nul(&self) -> &[u8] {
64        let ptr = self.ptr.as_ptr() as *const u8;
65        unsafe { core::slice::from_raw_parts(ptr, self.len + 1) }
66    }
67}
68
69impl Deref for DuckDbString {
70    type Target = std::ffi::CStr;
71
72    fn deref(&self) -> &Self::Target {
73        let bytes = self.to_bytes_with_nul();
74        unsafe { CStr::from_bytes_with_nul_unchecked(bytes) }
75    }
76}
77
78impl Drop for DuckDbString {
79    fn drop(&mut self) {
80        let ptr = self.ptr.as_ptr() as *mut core::ffi::c_void;
81        unsafe { duckdb_free(ptr) };
82    }
83}
84
85#[cfg(test)]
86mod tests {
87    use super::DuckDbString;
88
89    #[test]
90    fn from_nullable_ptr_returns_none_for_null() {
91        assert!(unsafe { DuckDbString::from_nullable_ptr(std::ptr::null()) }.is_none());
92    }
93}
libduckdb_sys/string.rs

libduckdb_sys/
string.rs
