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}