Skip to main content

ScalarOverloadBuilder

Struct ScalarOverloadBuilder 

Source
pub struct ScalarOverloadBuilder { /* private fields */ }
Expand description

A builder for one overload within a ScalarFunctionSetBuilder.

Implementations§

Source§

impl ScalarOverloadBuilder

Source

pub fn new() -> Self

Creates a new ScalarOverloadBuilder.

Source

pub fn param(self, type_id: TypeId) -> Self

Adds a positional parameter to this overload.

For complex types like LIST(BIGINT), use param_logical.

Source

pub fn param_logical(self, logical_type: LogicalType) -> Self

Adds a positional parameter with a complex LogicalType.

Use this for parameterized types that TypeId cannot express, such as LIST(BIGINT), MAP(VARCHAR, INTEGER), or STRUCT(...).

Source

pub const fn returns(self, type_id: TypeId) -> Self

Sets the return type for this overload.

For complex return types like LIST(BIGINT), use returns_logical instead.

Source

pub fn returns_logical(self, logical_type: LogicalType) -> Self

Sets the return type to a complex LogicalType for this overload.

Use this for parameterized return types that TypeId cannot express, such as LIST(BOOLEAN), LIST(TIMESTAMP), MAP(VARCHAR, INTEGER), etc.

If both returns and returns_logical are called, the logical type takes precedence.

Source

pub fn function(self, f: ScalarFn) -> Self

Sets the scalar function callback for this overload.

Source

pub fn varargs(self, type_id: TypeId) -> Self

Marks this overload as accepting variadic arguments of the given type, after its fixed parameters.

Mirrors ScalarFunctionBuilder::varargs, including the error from register for a composite type_id.

Source

pub fn varargs_logical(self, logical_type: LogicalType) -> Self

Marks this overload as accepting variadic arguments with a complex type.

Mirrors ScalarFunctionBuilder::varargs_logical.

Source

pub const fn volatile(self) -> Self

Marks this overload as volatile: re-evaluated for every row even when its arguments are constant.

Mirrors ScalarFunctionBuilder::volatile. Each overload of a set has its own stability.

Source

pub fn bind(self, f: ScalarBindFn) -> Self

Sets a bind callback for this overload (DuckDB 1.5.0+).

Mirrors ScalarFunctionBuilder::bind.

Guard it against panics with scalar_bind_callback!, not table_bind_callback!. The compiler refuses the table macro here — its function takes a table function’s bind info, not a RawScalarBindInfo — because a table callback reports a panic through duckdb_bind_set_error, which would write past the smaller scalar bind info and corrupt the stack.

Source

pub fn init(self, f: ScalarInitFn) -> Self

Sets an init callback for this overload (DuckDB 1.5.0+).

Mirrors ScalarFunctionBuilder::init.

Guard it against panics with scalar_init_callback!, not table_init_callback!. The compiler refuses the table macro here — its function takes a table function’s init info, not a RawScalarInitInfo — because a table callback reports a panic through duckdb_init_set_error, which would write past the smaller scalar init info and corrupt the stack.

Source

pub const fn null_handling(self, handling: NullHandling) -> Self

Sets the NULL handling behaviour for this overload.

Under either setting the callback receives NULL rows. With the default, DefaultNullHandling, the callback promises NULL-in-NULL-out and must keep that promise itself — DuckDB does not write NULL for it (pitfall L8; see NullHandling and DataChunk::propagate_nulls). SpecialNullHandling declares that it may return non-NULL for NULL input.

Source

pub unsafe fn extra_info( self, data: *mut c_void, destroy: duckdb_delete_callback_t, ) -> Self

Attaches arbitrary data to this overload.

The data pointer is available inside the callback via duckdb_function_get_extra_info. The destroy callback is called by DuckDB when the function is dropped to free the data.

§Safety
  • data must stay valid until destroy frees it (with no destroy, for as long as the database lives), and destroy must be able to free it exactly once with no one else freeing it — so one pointer must not be given to two builders or overloads, each of which hands its destroy to DuckDB separately.
  • The pointee must be Send + Sync. DuckDB hands the same pointer to the callbacks on every thread that executes the function, possibly at the same moment, and destroy runs on whichever thread releases the function — or, if the builder is dropped unregistered, the thread that drops it.
  • destroy must not unwind: it is an extern "C" fn, so a panic escaping it aborts the process. Wrap a body that can panic in catch_ffi_panic.

The typical pattern is to box your data: Box::into_raw(Box::new(my_data)).cast().

Trait Implementations§

Source§

impl Debug for ScalarOverloadBuilder

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for ScalarOverloadBuilder

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.