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;