Skip to main content

quack_rs/scalar/
typed.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//! Scalar functions written as ordinary Rust closures.
7//!
8//! [`ScalarFunctionBuilder::function`][crate::scalar::ScalarFunctionBuilder::function]
9//! takes an `unsafe extern "C" fn`, which means every scalar function — the most
10//! common kind of extension function by far — starts with raw pointers, manual
11//! offset arithmetic, and the NULL-propagation contract described in
12//! [`NullHandling`]. The constructors here take a
13//! safe closure instead:
14//!
15//! ```rust,no_run
16//! use quack_rs::scalar::ScalarFunctionBuilder;
17//!
18//! # fn demo(con: libduckdb_sys::duckdb_connection)
19//! # -> Result<(), quack_rs::error::ExtensionError> {
20//! // SAFETY: `con` is the connection DuckDB handed the entry point.
21//! unsafe {
22//!     ScalarFunctionBuilder::map1("double_it", |x: i64| x * 2)?.register(con)?;
23//!     ScalarFunctionBuilder::map2("add", |a: i64, b: i64| a + b)?.register(con)?;
24//!     ScalarFunctionBuilder::map1_str("shout", |s: &str| s.to_uppercase())?
25//!         .register(con)?;
26//!     // `None` is SQL NULL.
27//!     ScalarFunctionBuilder::map1_str("email_domain", |s: &str| {
28//!         s.split_once('@').map(|(_, domain)| domain.to_owned())
29//!     })?
30//!     .register(con)?;
31//!     // `Err` fails the query with its message.
32//!     ScalarFunctionBuilder::try_map1_str("parse_int", |s: &str| s.trim().parse::<i64>())?
33//!         .register(con)?;
34//! }
35//! # Ok(())
36//! # }
37//! ```
38//!
39//! # What they take care of
40//!
41//! - **Types.** Parameter and return types are derived from the closure's
42//!   signature, so a mismatch is a compile error rather than a registration
43//!   failure or a misread vector.
44//! - **NULLs.** `map1` / `map2` / `map3` / `map1_str` / `map2_str` and their
45//!   `try_*` forms implement SQL's NULL-in-NULL-out: a row with any NULL
46//!   argument is skipped and its result set NULL. `DuckDB` does *not* do this for you — see
47//!   [`DataChunk::propagate_nulls`][crate::data_chunk::DataChunk::propagate_nulls].
48//!   The `*_opt` variants hand the closure `Option`s instead and register
49//!   [`SpecialNullHandling`][crate::types::NullHandling::SpecialNullHandling].
50//! - **NULL results.** Every constructor accepts a closure returning
51//!   `Option<R>`: `None` writes SQL NULL for that row. This is independent of
52//!   NULL *arguments* — the NULL-propagating constructors still never call the
53//!   closure for those.
54//! - **Panics and errors.** The closure runs inside `catch_unwind`, and a panic
55//!   becomes a `DuckDB` error on that query rather than a process abort. The
56//!   `try_*` constructors ([`try_map1`][ScalarFunctionBuilder::try_map1],
57//!   [`try_map2`][ScalarFunctionBuilder::try_map2],
58//!   [`try_map3`][ScalarFunctionBuilder::try_map3],
59//!   [`try_map1_str`][ScalarFunctionBuilder::try_map1_str],
60//!   [`try_map2_str`][ScalarFunctionBuilder::try_map2_str]) take a closure
61//!   returning `Result<R, E>`; an `Err` fails the query with `E`'s `Display`
62//!   text. Return `Ok(None)` for NULL and `Err` for bad input.
63//! - **A fixed signature.** They return a
64//!   [`TypedScalarFunctionBuilder`], not a [`ScalarFunctionBuilder`]: it has no
65//!   `returns` / `param` / `function` / `extra_info`, because redeclaring the
66//!   signature after the fact would make the closure read and write vectors of
67//!   the wrong width. Register it with
68//!   [`TypedScalarFunctionBuilder::register`] or
69//!   [`Registrar::register_typed_scalar`][crate::connection::Registrar::register_typed_scalar].
70//!   To overload one name with several closures (one per argument type),
71//!   add each to one set with
72//!   [`ScalarFunctionSetBuilder::overload_typed`][crate::scalar::ScalarFunctionSetBuilder::overload_typed]:
73//!   before `DuckDB` v1.5.0 a second registration under a taken name fails.
74//!
75//! # Cost
76//!
77//! One indirect call per *chunk*, not per row: the closure is monomorphised into
78//! a per-chunk executor when the function is built, and only that executor is
79//! reached through `dyn`. The inner row loop is the same code the hand-written
80//! callback would have been.
81//!
82//! # When to drop down
83//!
84//! Reach for [`scalar_callback!`][crate::scalar_callback] and the raw builder
85//! when the function needs `STRUCT` / `LIST` / `MAP` arguments, variable arity,
86//! bind-time constant folding, or per-thread local state.
87
88use crate::error::ExtensionError;
89use crate::scalar::builder::ScalarFunctionBuilder;
90use crate::scalar::typed_builder::TypedScalarFunctionBuilder;
91use crate::types::{NullHandling, TypeId};
92use crate::vector::{VectorReader, VectorWriter};
93
94mod fallible;
95mod ternary;
96
97/// A Rust type that maps 1:1 onto a `DuckDB` scalar column type.
98///
99/// Implemented for `bool`, every signed and unsigned integer width `DuckDB` has
100/// (`i8`..`i128`, `u8`..`u128`), and `f32` / `f64`. These are the types the
101/// closure-based constructors accept as arguments.
102///
103/// # Safety
104///
105/// [`read`][Self::read] performs an unchecked typed read of a vector's data
106/// buffer. An implementation must return the type that
107/// [`type_id`][Self::type_id] names, or reads will silently reinterpret memory.
108/// This is why the trait is `unsafe` to implement; using it is entirely safe.
109pub unsafe trait ScalarValue: Copy + Send + Sync + 'static {
110    /// The `DuckDB` column type this maps to.
111    fn type_id() -> TypeId;
112
113    /// Reads row `row` of `reader` as `Self`.
114    ///
115    /// # Safety
116    ///
117    /// `reader` must cover a vector whose type is [`type_id`][Self::type_id],
118    /// and `row` must be within its row count.
119    unsafe fn read(reader: &VectorReader, row: usize) -> Self;
120}
121
122/// A Rust type a scalar closure can return.
123///
124/// Implemented for every [`ScalarValue`], plus `String` and `Vec<u8>` for
125/// `VARCHAR` and `BLOB` results, and for `Option<R>` of any of them: `None`
126/// writes SQL NULL for that row, so a closure can return NULL for some
127/// non-NULL inputs.
128///
129/// # Safety
130///
131/// [`write`][Self::write] performs an unchecked typed write into a vector's
132/// data buffer; see [`ScalarValue`].
133pub unsafe trait ScalarOut: Send + Sync + 'static {
134    /// The `DuckDB` column type this maps to.
135    fn type_id() -> TypeId;
136
137    /// Writes `value` into row `row` of `writer`.
138    ///
139    /// # Safety
140    ///
141    /// `writer` must cover a vector whose type is [`type_id`][Self::type_id],
142    /// and `row` must be within its capacity.
143    unsafe fn write(writer: &mut VectorWriter, row: usize, value: Self);
144}
145
146macro_rules! impl_scalar_value {
147    ($($rust:ty => $variant:ident, $read:ident, $write:ident;)*) => {
148        $(
149            // SAFETY: `type_id` names the DuckDB type whose physical layout
150            // `VectorReader::$read` and `VectorWriter::$write` are documented to
151            // read and write.
152            unsafe impl ScalarValue for $rust {
153                #[inline]
154                fn type_id() -> TypeId { TypeId::$variant }
155                #[inline]
156                unsafe fn read(reader: &VectorReader, row: usize) -> Self {
157                    // SAFETY: forwarded from this method's own contract.
158                    unsafe { reader.$read(row) }
159                }
160            }
161            // SAFETY: as above.
162            unsafe impl ScalarOut for $rust {
163                #[inline]
164                fn type_id() -> TypeId { TypeId::$variant }
165                #[inline]
166                unsafe fn write(writer: &mut VectorWriter, row: usize, value: Self) {
167                    // SAFETY: forwarded from this method's own contract.
168                    unsafe { writer.$write(row, value) };
169                }
170            }
171        )*
172    };
173}
174
175impl_scalar_value! {
176    bool => Boolean,   read_bool, write_bool;
177    i8   => TinyInt,   read_i8,   write_i8;
178    i16  => SmallInt,  read_i16,  write_i16;
179    i32  => Integer,   read_i32,  write_i32;
180    i64  => BigInt,    read_i64,  write_i64;
181    i128 => HugeInt,   read_i128, write_i128;
182    u8   => UTinyInt,  read_u8,   write_u8;
183    u16  => USmallInt, read_u16,  write_u16;
184    u32  => UInteger,  read_u32,  write_u32;
185    u64  => UBigInt,   read_u64,  write_u64;
186    u128 => UHugeInt,  read_u128, write_u128;
187    f32  => Float,     read_f32,  write_f32;
188    f64  => Double,    read_f64,  write_f64;
189}
190
191// SAFETY: `VectorWriter::write_varchar` writes a VARCHAR `duckdb_string_t`.
192unsafe impl ScalarOut for String {
193    #[inline]
194    fn type_id() -> TypeId {
195        TypeId::Varchar
196    }
197    #[inline]
198    unsafe fn write(writer: &mut VectorWriter, row: usize, value: Self) {
199        // SAFETY: forwarded from this method's own contract.
200        unsafe { writer.write_varchar(row, &value) };
201    }
202}
203
204// SAFETY: `VectorWriter::write_blob` writes a BLOB `duckdb_string_t`.
205unsafe impl ScalarOut for Vec<u8> {
206    #[inline]
207    fn type_id() -> TypeId {
208        TypeId::Blob
209    }
210    #[inline]
211    unsafe fn write(writer: &mut VectorWriter, row: usize, value: Self) {
212        // SAFETY: forwarded from this method's own contract.
213        unsafe { writer.write_blob(row, &value) };
214    }
215}
216
217/// `None` is SQL NULL.
218///
219/// The column type is `R`'s; `Some(v)` writes `v` exactly as `R` would, and
220/// `None` marks the row NULL through [`VectorWriter::set_null`]. This lets
221/// [`map1`][ScalarFunctionBuilder::map1] and its siblings return NULL for an
222/// input that is not NULL — `map1_str("domain", |s: &str| s.split_once('@')
223/// .map(|(_, d)| d.to_owned()))` — without dropping to
224/// [`scalar_callback!`][crate::scalar_callback].
225///
226/// It does not change how NULL *arguments* are treated: the NULL-propagating
227/// constructors still skip a row with a NULL argument and write NULL without
228/// calling the closure. Use the `*_opt` constructors to see NULL arguments.
229// SAFETY: both arms uphold `R::write`'s contract: `Some` forwards to it with
230// the same writer and row, and `None` only touches the validity mask of a row
231// the caller guarantees is in bounds. `type_id` is `R`'s, so the vector the
232// caller provides is the one `R::write` expects.
233unsafe impl<R: ScalarOut> ScalarOut for Option<R> {
234    #[inline]
235    fn type_id() -> TypeId {
236        R::type_id()
237    }
238    #[inline]
239    unsafe fn write(writer: &mut VectorWriter, row: usize, value: Self) {
240        match value {
241            // SAFETY: forwarded from this method's own contract; the vector's
242            // type is `R::type_id()`.
243            Some(value) => unsafe { R::write(writer, row, value) },
244            // SAFETY: `row` is within the vector's capacity per this method's
245            // contract.
246            None => unsafe { writer.set_null(row) },
247        }
248    }
249}
250
251impl ScalarFunctionBuilder {
252    /// A unary scalar function from a safe closure, with SQL NULL propagation.
253    ///
254    /// Parameter and return types come from the closure's signature. A row whose
255    /// argument is NULL yields NULL without calling the closure.
256    ///
257    /// # Errors
258    ///
259    /// Returns an error if `name` is not a valid SQL identifier.
260    ///
261    /// # Example
262    ///
263    /// ```rust,no_run
264    /// use quack_rs::scalar::ScalarFunctionBuilder;
265    ///
266    /// # fn demo(con: libduckdb_sys::duckdb_connection)
267    /// # -> Result<(), quack_rs::error::ExtensionError> {
268    /// // SAFETY: `con` is the connection DuckDB handed the entry point.
269    /// unsafe { ScalarFunctionBuilder::map1("double_it", |x: i64| x * 2)?.register(con) }
270    /// # }
271    /// ```
272    pub fn map1<A, R, F>(name: &str, f: F) -> Result<TypedScalarFunctionBuilder, ExtensionError>
273    where
274        A: ScalarValue,
275        R: ScalarOut,
276        F: Fn(A) -> R + Send + Sync + 'static,
277    {
278        TypedScalarFunctionBuilder::from_exec(
279            name,
280            &[A::type_id()],
281            R::type_id(),
282            NullHandling::DefaultNullHandling,
283            Box::new(move |chunk, writer| {
284                // SAFETY: DuckDB declared one parameter, so column 0 exists and
285                // has the type `A::type_id()` named at registration.
286                let a = unsafe { chunk.reader(0) };
287                for row in 0..chunk.size() {
288                    // SAFETY: `row` is within the chunk.
289                    if unsafe { a.is_valid(row) } {
290                        // SAFETY: the column's type was declared as `A`.
291                        let value = f(unsafe { A::read(&a, row) });
292                        // SAFETY: the result vector's type was declared as `R`.
293                        unsafe { R::write(writer, row, value) };
294                    } else {
295                        // SAFETY: `row` is within the output vector.
296                        unsafe { writer.set_null(row) };
297                    }
298                }
299                Ok(())
300            }),
301        )
302    }
303
304    /// A binary scalar function from a safe closure, with SQL NULL propagation.
305    ///
306    /// A row with either argument NULL yields NULL without calling the closure.
307    ///
308    /// # Errors
309    ///
310    /// Returns an error if `name` is not a valid SQL identifier.
311    // The per-row NULL-propagation test `a.is_valid(row) && b.is_valid(row)`
312    // lives in a closure that only ever runs inside DuckDB's expression
313    // executor, so a `--lib` run cannot reach it and the `&& -> ||` mutant
314    // survives there. It does not survive the end-to-end suite:
315    // `typed_scalar_closures_cover_the_common_shapes` in
316    // `tests/ffi_roundtrip.rs` asserts that map2 NULLs out a row where
317    // *either* argument is NULL, reading from a real column rather than a
318    // constant-folded literal.
319    #[cfg_attr(test, mutants::skip)]
320    pub fn map2<A, B, R, F>(name: &str, f: F) -> Result<TypedScalarFunctionBuilder, ExtensionError>
321    where
322        A: ScalarValue,
323        B: ScalarValue,
324        R: ScalarOut,
325        F: Fn(A, B) -> R + Send + Sync + 'static,
326    {
327        TypedScalarFunctionBuilder::from_exec(
328            name,
329            &[A::type_id(), B::type_id()],
330            R::type_id(),
331            NullHandling::DefaultNullHandling,
332            Box::new(move |chunk, writer| {
333                // SAFETY: two parameters were declared, so both columns exist
334                // with the types named at registration.
335                let (a, b) = unsafe { (chunk.reader(0), chunk.reader(1)) };
336                for row in 0..chunk.size() {
337                    // SAFETY: `row` is within the chunk.
338                    if unsafe { a.is_valid(row) && b.is_valid(row) } {
339                        // SAFETY: the columns' types were declared as `A` and `B`.
340                        let value = unsafe { f(A::read(&a, row), B::read(&b, row)) };
341                        // SAFETY: the result vector's type was declared as `R`.
342                        unsafe { R::write(writer, row, value) };
343                    } else {
344                        // SAFETY: `row` is within the output vector.
345                        unsafe { writer.set_null(row) };
346                    }
347                }
348                Ok(())
349            }),
350        )
351    }
352
353    /// A unary scalar function that **sees** NULLs.
354    ///
355    /// Registers
356    /// [`SpecialNullHandling`][crate::types::NullHandling::SpecialNullHandling],
357    /// so `DuckDB` neither expects nor asserts NULL-in-NULL-out. The closure
358    /// receives `None` for a NULL argument and returning `None` writes NULL —
359    /// which is what `coalesce`-like and `is_null`-like functions need.
360    ///
361    /// # Errors
362    ///
363    /// Returns an error if `name` is not a valid SQL identifier.
364    pub fn map1_opt<A, R, F>(name: &str, f: F) -> Result<TypedScalarFunctionBuilder, ExtensionError>
365    where
366        A: ScalarValue,
367        R: ScalarOut,
368        F: Fn(Option<A>) -> Option<R> + Send + Sync + 'static,
369    {
370        TypedScalarFunctionBuilder::from_exec(
371            name,
372            &[A::type_id()],
373            R::type_id(),
374            NullHandling::SpecialNullHandling,
375            Box::new(move |chunk, writer| {
376                // SAFETY: one parameter was declared, so column 0 exists.
377                let a = unsafe { chunk.reader(0) };
378                for row in 0..chunk.size() {
379                    // SAFETY: `row` is within the chunk; the column's type was
380                    // declared as `A`.
381                    let arg = unsafe { a.is_valid(row).then(|| A::read(&a, row)) };
382                    match f(arg) {
383                        // SAFETY: the result vector's type was declared as `R`.
384                        Some(value) => unsafe { R::write(writer, row, value) },
385                        // SAFETY: `row` is within the output vector.
386                        None => unsafe { writer.set_null(row) },
387                    }
388                }
389                Ok(())
390            }),
391        )
392    }
393
394    /// A binary scalar function that **sees** NULLs.
395    ///
396    /// See [`map1_opt`][Self::map1_opt].
397    ///
398    /// # Errors
399    ///
400    /// Returns an error if `name` is not a valid SQL identifier.
401    pub fn map2_opt<A, B, R, F>(
402        name: &str,
403        f: F,
404    ) -> Result<TypedScalarFunctionBuilder, ExtensionError>
405    where
406        A: ScalarValue,
407        B: ScalarValue,
408        R: ScalarOut,
409        F: Fn(Option<A>, Option<B>) -> Option<R> + Send + Sync + 'static,
410    {
411        TypedScalarFunctionBuilder::from_exec(
412            name,
413            &[A::type_id(), B::type_id()],
414            R::type_id(),
415            NullHandling::SpecialNullHandling,
416            Box::new(move |chunk, writer| {
417                // SAFETY: two parameters were declared, so both columns exist.
418                let (left, right) = unsafe { (chunk.reader(0), chunk.reader(1)) };
419                for row in 0..chunk.size() {
420                    // SAFETY: `row` is within the chunk; the columns' types were
421                    // declared as `A` and `B`.
422                    let args = unsafe {
423                        (
424                            left.is_valid(row).then(|| A::read(&left, row)),
425                            right.is_valid(row).then(|| B::read(&right, row)),
426                        )
427                    };
428                    match f(args.0, args.1) {
429                        // SAFETY: the result vector's type was declared as `R`.
430                        Some(value) => unsafe { R::write(writer, row, value) },
431                        // SAFETY: `row` is within the output vector.
432                        None => unsafe { writer.set_null(row) },
433                    }
434                }
435                Ok(())
436            }),
437        )
438    }
439
440    /// A `VARCHAR`-argument scalar function from a safe closure, with SQL NULL
441    /// propagation.
442    ///
443    /// The closure borrows the string straight out of the vector — no allocation
444    /// per row. `VARCHAR` needs its own constructor because the argument is a
445    /// borrow with the chunk's lifetime, which a plain type parameter cannot
446    /// express.
447    ///
448    /// # Errors
449    ///
450    /// Returns an error if `name` is not a valid SQL identifier.
451    ///
452    /// # Example
453    ///
454    /// ```rust,no_run
455    /// use quack_rs::scalar::ScalarFunctionBuilder;
456    ///
457    /// # fn demo(con: libduckdb_sys::duckdb_connection)
458    /// # -> Result<(), quack_rs::error::ExtensionError> {
459    /// // SAFETY: `con` is the connection DuckDB handed the entry point.
460    /// unsafe {
461    ///     ScalarFunctionBuilder::map1_str("word_count", |s: &str| {
462    ///         s.split_whitespace().count() as i64
463    ///     })?
464    ///     .register(con)
465    /// }
466    /// # }
467    /// ```
468    pub fn map1_str<R, F>(name: &str, f: F) -> Result<TypedScalarFunctionBuilder, ExtensionError>
469    where
470        R: ScalarOut,
471        F: for<'a> Fn(&'a str) -> R + Send + Sync + 'static,
472    {
473        TypedScalarFunctionBuilder::from_exec(
474            name,
475            &[TypeId::Varchar],
476            R::type_id(),
477            NullHandling::DefaultNullHandling,
478            Box::new(move |chunk, writer| {
479                // SAFETY: one VARCHAR parameter was declared, so column 0 exists
480                // and holds VARCHAR.
481                let a = unsafe { chunk.reader(0) };
482                for row in 0..chunk.size() {
483                    // SAFETY: `row` is within the chunk.
484                    if unsafe { a.is_valid(row) } {
485                        // SAFETY: the column was declared VARCHAR; the borrow
486                        // ends before the chunk does.
487                        let value = f(unsafe { a.read_str(row) });
488                        // SAFETY: the result vector's type was declared as `R`.
489                        unsafe { R::write(writer, row, value) };
490                    } else {
491                        // SAFETY: `row` is within the output vector.
492                        unsafe { writer.set_null(row) };
493                    }
494                }
495                Ok(())
496            }),
497        )
498    }
499
500    /// A two-`VARCHAR` scalar function from a safe closure, with SQL NULL
501    /// propagation.
502    ///
503    /// See [`map1_str`][Self::map1_str].
504    ///
505    /// # Errors
506    ///
507    /// Returns an error if `name` is not a valid SQL identifier.
508    // The per-row NULL-propagation test `a.is_valid(row) && b.is_valid(row)`
509    // lives in a closure that only ever runs inside DuckDB's expression
510    // executor, so a `--lib` run cannot reach it and the `&& -> ||` mutant
511    // survives there. It does not survive the end-to-end suite:
512    // `typed_scalar_closures_cover_the_common_shapes` in
513    // `tests/ffi_roundtrip.rs` asserts that map2_str NULLs out a row where
514    // *either* argument is NULL, reading from a real column rather than a
515    // constant-folded literal.
516    #[cfg_attr(test, mutants::skip)]
517    pub fn map2_str<R, F>(name: &str, f: F) -> Result<TypedScalarFunctionBuilder, ExtensionError>
518    where
519        R: ScalarOut,
520        F: for<'a, 'b> Fn(&'a str, &'b str) -> R + Send + Sync + 'static,
521    {
522        TypedScalarFunctionBuilder::from_exec(
523            name,
524            &[TypeId::Varchar, TypeId::Varchar],
525            R::type_id(),
526            NullHandling::DefaultNullHandling,
527            Box::new(move |chunk, writer| {
528                // SAFETY: two VARCHAR parameters were declared.
529                let (a, b) = unsafe { (chunk.reader(0), chunk.reader(1)) };
530                for row in 0..chunk.size() {
531                    // SAFETY: `row` is within the chunk.
532                    if unsafe { a.is_valid(row) && b.is_valid(row) } {
533                        // SAFETY: both columns were declared VARCHAR.
534                        let value = unsafe { f(a.read_str(row), b.read_str(row)) };
535                        // SAFETY: the result vector's type was declared as `R`.
536                        unsafe { R::write(writer, row, value) };
537                    } else {
538                        // SAFETY: `row` is within the output vector.
539                        unsafe { writer.set_null(row) };
540                    }
541                }
542                Ok(())
543            }),
544        )
545    }
546}
547
548#[cfg(test)]
549mod tests;