Skip to main content

quack_rs/scalar/builder/
set.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
6use std::ffi::CString;
7
8use libduckdb_sys::{
9    duckdb_add_scalar_function_to_set, duckdb_connection, duckdb_create_scalar_function,
10    duckdb_create_scalar_function_set, duckdb_destroy_scalar_function,
11    duckdb_destroy_scalar_function_set, duckdb_register_scalar_function_set,
12    duckdb_scalar_function_add_parameter, duckdb_scalar_function_set_extra_info,
13    duckdb_scalar_function_set_function, duckdb_scalar_function_set_name,
14    duckdb_scalar_function_set_return_type, duckdb_scalar_function_set_special_handling,
15    duckdb_scalar_function_set_volatile, DuckDBSuccess,
16};
17#[cfg(feature = "duckdb-1-5")]
18use libduckdb_sys::{duckdb_scalar_function_set_bind, duckdb_scalar_function_set_init};
19
20use crate::error::ExtensionError;
21use crate::scalar::TypedScalarFunctionBuilder;
22use crate::types::logical_type::SlotCheck;
23use crate::types::{LogicalType, NullHandling};
24use crate::validate::validate_function_name;
25
26use super::overload::{ScalarOverloadBuilder, ScalarOverloadSpec};
27use super::signature::{merged_params, reject_duplicate_overloads};
28
29/// Builder for registering a `DuckDB` scalar function set (multiple overloads).
30///
31/// Use this when your scalar function accepts different parameter types or arities
32/// by registering N overloads under a single name.
33///
34/// # Pitfall L6 (applies to scalar sets too)
35///
36/// This builder calls `duckdb_scalar_function_set_name` on EVERY individual
37/// function before adding it to the set, matching the pattern established by
38/// [`AggregateFunctionSetBuilder`][crate::aggregate::AggregateFunctionSetBuilder].
39///
40/// # Example
41///
42/// ```rust,no_run
43/// use quack_rs::scalar::{ScalarFunctionSetBuilder, ScalarOverloadBuilder};
44/// use quack_rs::types::TypeId;
45/// use libduckdb_sys::{duckdb_connection, duckdb_function_info, duckdb_data_chunk,
46///                     duckdb_vector};
47///
48/// unsafe extern "C" fn add_ints(
49///     _: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector,
50/// ) {}
51/// unsafe extern "C" fn add_doubles(
52///     _: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector,
53/// ) {}
54///
55/// // fn register(con: duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
56/// //     unsafe {
57/// //         ScalarFunctionSetBuilder::new("my_add")
58/// //             .overload(
59/// //                 ScalarOverloadBuilder::new()
60/// //                     .param(TypeId::Integer).param(TypeId::Integer)
61/// //                     .returns(TypeId::Integer)
62/// //                     .function(add_ints)
63/// //             )
64/// //             .overload(
65/// //                 ScalarOverloadBuilder::new()
66/// //                     .param(TypeId::Double).param(TypeId::Double)
67/// //                     .returns(TypeId::Double)
68/// //                     .function(add_doubles)
69/// //             )
70/// //             .register(con)
71/// //     }
72/// // }
73/// ```
74#[must_use]
75pub struct ScalarFunctionSetBuilder {
76    pub(super) name: CString,
77    pub(super) overloads: Vec<ScalarOverloadSpec>,
78}
79
80impl ScalarFunctionSetBuilder {
81    /// Creates a new builder for a scalar function set with the given name.
82    ///
83    /// # Panics
84    ///
85    /// Panics if `name` contains an interior null byte.
86    pub fn new(name: &str) -> Self {
87        Self {
88            name: CString::new(name).expect("function name must not contain null bytes"),
89            overloads: Vec::new(),
90        }
91    }
92
93    /// Creates a new builder with function name validation.
94    ///
95    /// # Errors
96    ///
97    /// Returns `ExtensionError` if the name is invalid.
98    /// See [`validate_function_name`] for the full set of rules.
99    pub fn try_new(name: &str) -> Result<Self, ExtensionError> {
100        validate_function_name(name)?;
101        let c_name = CString::new(name)
102            .map_err(|_| ExtensionError::new("function name contains interior null byte"))?;
103        Ok(Self {
104            name: c_name,
105            overloads: Vec::new(),
106        })
107    }
108
109    /// Returns the function set name.
110    ///
111    /// Useful for introspection and for [`MockRegistrar`][crate::testing::MockRegistrar].
112    pub fn name(&self) -> &str {
113        self.name.to_str().unwrap_or("")
114    }
115
116    /// Adds a single overload to this function set.
117    pub fn overload(mut self, builder: ScalarOverloadBuilder) -> Self {
118        self.overloads.push(builder.into_spec());
119        self
120    }
121
122    /// Adds a closure-built function ([`ScalarFunctionBuilder::map1`] and
123    /// its siblings) as one overload of this set.
124    ///
125    /// This is how a closure-built function gets overloads: one set holding
126    /// one closure per argument type, registered once. Registering several
127    /// closure-built functions under one name one by one works only from
128    /// `DuckDB` v1.5.0 (before it, the C API cannot add an overload to an
129    /// existing name), and this works on every engine.
130    ///
131    /// The overload keeps what the closure fixed — its parameter and return
132    /// types, callback and `extra_info` — and its stability
133    /// ([`volatile`][TypedScalarFunctionBuilder::volatile]); the set offers no
134    /// way to change them. It takes the set's name: one built under another
135    /// name (compared case-insensitively, as `DuckDB` compares names) makes
136    /// [`register`][Self::register] fail, naming the overload, rather than
137    /// register it as something its builder did not say.
138    ///
139    /// ```rust,no_run
140    /// use quack_rs::scalar::{ScalarFunctionBuilder, ScalarFunctionSetBuilder};
141    ///
142    /// # fn demo(con: libduckdb_sys::duckdb_connection) -> Result<(), quack_rs::error::ExtensionError> {
143    /// let set = ScalarFunctionSetBuilder::new("double_it")
144    ///     .overload_typed(ScalarFunctionBuilder::map1("double_it", |x: i32| x.wrapping_mul(2))?)
145    ///     .overload_typed(ScalarFunctionBuilder::map1("double_it", |x: i64| x.wrapping_mul(2))?)
146    ///     .overload_typed(ScalarFunctionBuilder::map1("double_it", |x: f64| x * 2.0)?);
147    /// // SAFETY: `con` is an open connection.
148    /// unsafe { set.register(con) }
149    /// # }
150    /// ```
151    ///
152    /// [`ScalarFunctionBuilder::map1`]: super::ScalarFunctionBuilder::map1
153    pub fn overload_typed(mut self, function: TypedScalarFunctionBuilder) -> Self {
154        self.overloads
155            .push(ScalarOverloadSpec::from_function(function.into_inner()));
156        self
157    }
158
159    /// Registers the scalar function set on the given connection.
160    ///
161    /// # Errors
162    ///
163    /// Returns `ExtensionError` if:
164    /// - No overloads were added.
165    /// - A parameter, varargs or return type was given as a bare composite
166    ///   [`TypeId`][crate::types::TypeId] (`DECIMAL`, `ENUM`, `LIST`, `STRUCT`, `MAP`, `ARRAY`,
167    ///   `UNION`), which carries parameters a `TypeId` cannot express. Build
168    ///   it as a [`LogicalType`] and use the `*_logical` method; the error
169    ///   names the slot.
170    /// - Any overload is missing a return type or function callback. The error
171    ///   names the overload's index, and is reported before any `DuckDB`
172    ///   handle is allocated.
173    /// - Two overloads accept the same call: argument types `DuckDB`'s
174    ///   overload resolution cannot tell apart, or, with varargs, such types
175    ///   at some argument count (`f(BIGINT)` and `f(BIGINT, BIGINT...)` both
176    ///   take `f(1)`). It tells `DECIMAL`, `MAP` and `ENUM` parameters apart
177    ///   by type alone, also inside a `LIST`, `ARRAY`, `STRUCT` or `UNION`, so
178    ///   `DECIMAL(4,1)` and `DECIMAL(18,3)` collide, as do `MAP(VARCHAR,
179    ///   BIGINT)` and `MAP(BIGINT, VARCHAR)`; `LIST(INTEGER)` and
180    ///   `LIST(VARCHAR)` do not. `DuckDB` itself would accept such a set and
181    ///   then fail every such call with "Could not choose a best candidate
182    ///   function". The rule, and the two shapes it does not catch, are on
183    ///   `reject_duplicate_overloads` in `src/scalar/builder/signature.rs`.
184    /// - An overload accepts the same call as a scalar function that already
185    ///   exists (see "Name collisions").
186    /// - `DuckDB` reports registration failure.
187    ///
188    /// # Name collisions
189    ///
190    /// `DuckDB` registers scalar functions with `ALTER_ON_CONFLICT`
191    /// (`duckdb_register_scalar_function_set` in `scalar_function-c.cpp`), so a
192    /// **scalar** function that already has this name — built-in or not — never
193    /// makes `DuckDB` refuse the registration. A new signature is added as an
194    /// overload. One with the same parameter types as an existing overload
195    /// either **silently replaces it** for every connection to the database
196    /// (same return type: `FunctionSet::MergeFunctionSet` with
197    /// `override = true`) or makes every call ambiguous ("Could not choose a
198    /// best candidate function", different return type). Registering
199    /// `abs(BIGINT)` would change the built-in `abs` for `BIGINT`.
200    ///
201    /// quack-rs therefore refuses an overload, naming its index, before
202    /// registering, when `duckdb_functions()` already lists a scalar with this
203    /// name that accepts the same call — the rule and its coverage are those of
204    /// [`ScalarFunctionBuilder::register`][super::ScalarFunctionBuilder::register],
205    /// including its cost: one catalog scan per call, or one per extension load
206    /// through the entry point's [`Connection`](crate::connection::Connection).
207    /// `DuckDB` itself refuses a name that belongs to an aggregate function or
208    /// a macro (such as the built-in `list_sum`).
209    ///
210    /// # Safety
211    ///
212    /// `con` must be a valid, open `duckdb_connection`.
213    pub unsafe fn register(self, con: duckdb_connection) -> Result<(), ExtensionError> {
214        // SAFETY: forwarded from this function's own contract.
215        unsafe { self.register_with(con, None) }
216    }
217
218    /// The completeness checks that need no `DuckDB` call: at least one
219    /// overload, each with a return type and a function callback.
220    /// [`MockRegistrar`][crate::testing::MockRegistrar] runs them too.
221    pub(crate) fn check_parts(&self) -> Result<(), ExtensionError> {
222        if self.overloads.is_empty() {
223            return Err(ExtensionError::new(
224                "no overloads added to scalar function set",
225            ));
226        }
227        let name = self.name();
228        for (i, overload) in self.overloads.iter().enumerate() {
229            overload.check_complete(i)?;
230            if let Some(built_as) = &overload.built_as {
231                if built_as.to_lowercase() != name.to_lowercase() {
232                    return Err(ExtensionError::new(format!(
233                        "overload {i} is a closure-built function named '{built_as}', added to \
234                         the function set '{name}': build it under the set's name"
235                    )));
236                }
237            }
238        }
239        Ok(())
240    }
241
242    /// Refuses a type [`register`][Self::register] refuses before its first
243    /// `DuckDB` call; `slot` checks each `TypeId` (see [`SlotCheck`]).
244    pub(crate) fn check_types(&self, slot: SlotCheck) -> Result<(), ExtensionError> {
245        for (i, overload) in self.overloads.iter().enumerate() {
246            crate::table::type_check::refuse_any_return(
247                &format!("overload {i} return type"),
248                overload.return_type,
249                overload.return_logical.as_ref(),
250            )?;
251        }
252        for (i, overload) in self.overloads.iter().enumerate() {
253            for (j, id) in overload.params.iter().enumerate() {
254                slot(*id, &format!("overload {i} parameter {j}"))?;
255            }
256            if let Some(id) = overload.return_type {
257                slot(id, &format!("overload {i} return type"))?;
258            }
259            if let Some(ref varargs) = overload.varargs {
260                varargs.check(slot, &format!("overload {i} varargs"))?;
261            }
262        }
263        Ok(())
264    }
265
266    /// [`register`][Self::register], checking signatures against `snapshot`
267    /// (listed on first use) instead of listing the catalog for this call.
268    ///
269    /// # Safety
270    ///
271    /// As [`register`][Self::register].
272    #[allow(clippy::too_many_lines)]
273    pub(crate) unsafe fn register_with(
274        self,
275        con: duckdb_connection,
276        snapshot: Option<&std::cell::RefCell<Option<super::collision::ExistingScalars>>>,
277    ) -> Result<(), ExtensionError> {
278        // Validate everything before allocating any DuckDB handle. The checks
279        // that need no DuckDB call come first, so a missing callback is
280        // reported by index without touching the engine.
281        self.check_parts()?;
282        self.check_types(LogicalType::check_slot)?;
283        let signatures: Vec<_> = self
284            .overloads
285            .iter()
286            .map(|o| {
287                let mut params = merged_params(&o.params, &o.logical_params);
288                if let Some(ref varargs) = o.varargs {
289                    params.push(varargs.param_ref());
290                }
291                params
292            })
293            .collect();
294        // SAFETY: every logical parameter is a live `LogicalType` owned by this
295        // builder, and the caller's contract means the C API is initialised.
296        unsafe { reject_duplicate_overloads(&self.name.to_string_lossy(), &signatures)? };
297        let name = self.name.to_string_lossy().into_owned();
298        let rendered: Vec<_> = signatures
299            .iter()
300            .enumerate()
301            .map(|(i, signature)| {
302                // SAFETY: the logical parameters are live, as above.
303                (format!("overload {i}"), unsafe {
304                    super::collision::render_signature(signature)
305                })
306            })
307            .collect();
308        // SAFETY: `con` is valid per this function's contract.
309        unsafe { super::collision::refuse_taken_signatures(con, snapshot, &name, &rendered)? };
310
311        // SAFETY: Creates a new scalar function set handle.
312        let mut set = unsafe { duckdb_create_scalar_function_set(self.name.as_ptr()) };
313
314        let mut register_error: Option<ExtensionError> = None;
315
316        for overload in &self.overloads {
317            // Resolve return type: prefer explicit LogicalType over TypeId.
318            // `_ret_lt_owner` keeps the LogicalType alive when created from TypeId.
319            // The two `else` arms below cannot run: every overload was checked
320            // for a return type and a callback before the set was created.
321            let (_ret_lt_owner, ret_raw) = if let Some(ref lt) = overload.return_logical {
322                (None, lt.as_raw())
323            } else if let Some(id) = overload.return_type {
324                let lt = LogicalType::new(id);
325                let raw = lt.as_raw();
326                (Some(lt), raw)
327            } else {
328                register_error = Some(ExtensionError::new("overload missing return type"));
329                break;
330            };
331
332            let Some(function) = overload.function else {
333                register_error = Some(ExtensionError::new("overload missing function callback"));
334                break;
335            };
336
337            // SAFETY: Creates a new scalar function handle for this overload.
338            let mut func = unsafe { duckdb_create_scalar_function() };
339
340            // PITFALL L6: Must call this on EACH function, not just the set.
341            // SAFETY: `func` is the handle `duckdb_create_scalar_function` returned above
342            // (a fresh `new ScalarFunction`, scalar_function-c.cpp), destroyed only at the
343            // end of this iteration. `self.name` is a `CString`, so NUL-terminated and live
344            // for the call; `duckdb_scalar_function_set_name` copies it into
345            // `ScalarFunction::name`.
346            unsafe {
347                duckdb_scalar_function_set_name(func, self.name.as_ptr());
348            }
349
350            // Add parameters: merge simple TypeId params and complex LogicalType params
351            // in the order they were added (tracked by position).
352            {
353                let mut simple_idx = 0;
354                let mut logical_idx = 0;
355                let total = overload.params.len() + overload.logical_params.len();
356                for pos in 0..total {
357                    if logical_idx < overload.logical_params.len()
358                        && overload.logical_params[logical_idx].0 == pos
359                    {
360                        // SAFETY: `func` is the handle `duckdb_create_scalar_function`
361                        // returned above (a fresh `new ScalarFunction`,
362                        // scalar_function-c.cpp), destroyed only at the end of this
363                        // iteration. The type is a `LogicalType` owned by
364                        // `overload.logical_params`, so its handle is live for this borrow;
365                        // `duckdb_scalar_function_add_parameter` copies it
366                        // (`arguments.push_back(*logical_type)`), keeping no pointer.
367                        unsafe {
368                            duckdb_scalar_function_add_parameter(
369                                func,
370                                overload.logical_params[logical_idx].1.as_raw(),
371                            );
372                        }
373                        logical_idx += 1;
374                    } else if simple_idx < overload.params.len() {
375                        let lt = LogicalType::new(overload.params[simple_idx]);
376                        // SAFETY: `func` is the handle `duckdb_create_scalar_function`
377                        // returned above (a fresh `new ScalarFunction`,
378                        // scalar_function-c.cpp), destroyed only at the end of this
379                        // iteration. `lt` was created on the line above and is dropped only
380                        // after this call; `duckdb_scalar_function_add_parameter` copies
381                        // the type.
382                        unsafe {
383                            duckdb_scalar_function_add_parameter(func, lt.as_raw());
384                        }
385                        simple_idx += 1;
386                    }
387                }
388            }
389
390            // Set return type
391            // SAFETY: `func` is the handle `duckdb_create_scalar_function` returned above
392            // (a fresh `new ScalarFunction`, scalar_function-c.cpp), destroyed only at the
393            // end of this iteration. `ret_raw` borrows `overload.return_logical` (owned by
394            // the builder) or `_ret_lt_owner`, both alive to the end of this iteration;
395            // `SetReturnType` copies the type.
396            unsafe {
397                duckdb_scalar_function_set_return_type(func, ret_raw);
398            }
399
400            // Set callback
401            // SAFETY: `func` is the handle `duckdb_create_scalar_function` returned above
402            // (a fresh `new ScalarFunction`, scalar_function-c.cpp), destroyed only at the
403            // end of this iteration. `function` is a non-null `ScalarFn` (an `extern "C"`
404            // fn pointer with the signature DuckDB calls); DuckDB only stores it in the
405            // function's `CScalarFunctionInfo`.
406            unsafe {
407                duckdb_scalar_function_set_function(func, Some(function));
408            }
409
410            // Set special NULL handling if requested
411            if overload.null_handling == NullHandling::SpecialNullHandling {
412                // SAFETY: func is a valid scalar function handle.
413                unsafe {
414                    duckdb_scalar_function_set_special_handling(func);
415                }
416            }
417
418            // Set bind / init callbacks if configured (`DuckDB` 1.5.0+)
419            #[cfg(feature = "duckdb-1-5")]
420            if let Some(bind_fn) = overload.bind {
421                // SAFETY: func is a valid scalar function handle.
422                unsafe {
423                    duckdb_scalar_function_set_bind(func, Some(super::single::raw_bind(bind_fn)));
424                }
425            }
426            #[cfg(feature = "duckdb-1-5")]
427            if let Some(init_fn) = overload.init {
428                // SAFETY: func is a valid scalar function handle.
429                unsafe {
430                    duckdb_scalar_function_set_init(func, Some(super::single::raw_init(init_fn)));
431                }
432            }
433
434            // Set varargs type if configured (stable C API since v1.2.0)
435            if let Some(ref varargs) = overload.varargs {
436                // SAFETY: func is a valid scalar function handle, and every
437                // overload's varargs type was checked above.
438                unsafe { varargs.set_on(func) };
439            }
440
441            // Set volatile flag if configured (stable C API since v1.2.0)
442            if overload.volatile {
443                // SAFETY: func is a valid scalar function handle.
444                unsafe {
445                    duckdb_scalar_function_set_volatile(func);
446                }
447            }
448
449            // Set extra info if provided
450            if let Some(info) = &overload.extra_info {
451                // SAFETY: func is valid; data and destroy are provided by caller.
452                unsafe {
453                    duckdb_scalar_function_set_extra_info(func, info.data(), info.destroy());
454                    // DuckDB owns the allocation from here.
455                    info.mark_transferred();
456                }
457            }
458
459            // Add to set
460            // SAFETY: `func` is the handle `duckdb_create_scalar_function` returned above
461            // (a fresh `new ScalarFunction`, scalar_function-c.cpp), destroyed only at the
462            // end of this iteration. `set` came from `duckdb_create_scalar_function_set`,
463            // which returns null only for an empty name, and this call null-checks both
464            // handles (returning `DuckDBError`). `AddFunction(T function)` takes the
465            // function by value (function_set.hpp), so the set keeps its own copy, not
466            // `func`.
467            unsafe {
468                duckdb_add_scalar_function_to_set(set, func);
469            }
470
471            // Destroy individual function (ownership transferred to set)
472            // SAFETY: `func` is the handle `duckdb_create_scalar_function` returned above
473            // (a fresh `new ScalarFunction`, scalar_function-c.cpp), destroyed only at the
474            // end of this iteration. The set holds its own copy of the function (and shares
475            // the extra info through its `shared_ptr`), so this single destroy of `func`
476            // frees nothing the set uses; it also nulls `func`.
477            unsafe {
478                duckdb_destroy_scalar_function(&raw mut func);
479            }
480        }
481
482        if register_error.is_none() {
483            // SAFETY: `con` is a valid, open connection per this function's `# Safety`
484            // clause. `set` is the set created above, not yet destroyed (the null an empty
485            // name yields is refused by DuckDB's own null check). Registration copies the
486            // set into the catalog (`CreateScalarFunctionInfo`) and catches its own
487            // exceptions, so destroying `set` below is still ours to do.
488            let result = unsafe { duckdb_register_scalar_function_set(con, set) };
489            if result != DuckDBSuccess {
490                register_error = Some(ExtensionError::new(format!(
491                    "duckdb_register_scalar_function_set failed for '{name}': {hint}",
492                    hint = crate::error::REGISTRATION_FAILURE_HINT
493                )));
494            }
495        }
496
497        // SAFETY: set was created above and must be destroyed.
498        unsafe {
499            duckdb_destroy_scalar_function_set(&raw mut set);
500        }
501
502        register_error.map_or_else(
503            || {
504                super::collision::record_registered(snapshot, &name, rendered);
505                Ok(())
506            },
507            Err,
508        )
509    }
510}
511
512impl core::fmt::Debug for ScalarFunctionSetBuilder {
513    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
514        f.debug_struct("ScalarFunctionSetBuilder")
515            .field("name", &self.name)
516            .field("overloads", &self.overloads.len())
517            .finish()
518    }
519}