Skip to main content

CastFunctionBuilder

Struct CastFunctionBuilder 

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

Builder for registering a custom DuckDB cast function.

A cast function converts values from a source type to a target type. Registering a cast lets DuckDB use it both for explicit CAST(x AS Target) syntax and (if an implicit cost is set) for automatic coercions.

§Example

use quack_rs::cast::{CastFunctionBuilder, CastFunctionInfo, CastMode};
use quack_rs::types::TypeId;
use libduckdb_sys::{duckdb_function_info, duckdb_vector, idx_t};

unsafe extern "C" fn my_cast(
    _info: duckdb_function_info,
    _count: idx_t,
    _input: duckdb_vector,
    _output: duckdb_vector,
) -> bool {
    true // implement real conversion here
}

// fn register(con: libduckdb_sys::duckdb_connection)
//     -> Result<(), quack_rs::error::ExtensionError>
// {
//     unsafe {
//         CastFunctionBuilder::new(TypeId::Varchar, TypeId::Integer)
//             .function(my_cast)
//             .register(con)
//     }
// }

Implementations§

Source§

impl CastFunctionBuilder

Source

pub const fn new(source: TypeId, target: TypeId) -> Self

Creates a new builder that will cast source values into target values.

Source

pub fn new_logical(source: LogicalType, target: LogicalType) -> Self

Creates a new builder using LogicalTypes for source and target.

Use this when the source or target types are complex (e.g. DECIMAL(18, 3), LIST(VARCHAR), etc.) and cannot be expressed as simple TypeId values.

Source

pub const fn source(&self) -> Option<TypeId>

Returns the source type this cast converts from (if set via new).

Returns None if the source was set via new_logical.

Useful for introspection and for MockRegistrar.

Source

pub const fn target(&self) -> Option<TypeId>

Returns the target type this cast converts to (if set via new).

Returns None if the target was set via new_logical.

Useful for introspection and for MockRegistrar.

Source

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

Sets the cast callback.

Source

pub const fn implicit_cost(self, cost: i64) -> Self

Sets the implicit cast cost.

When a non-negative cost is provided, DuckDB may use this cast automatically in expressions where an implicit coercion is needed. Lower cost means higher priority. A negative cost or omitting this method makes the cast explicit-only.

Source

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

Attaches extra data to the cast function.

The pointer is available inside the callback via CastFunctionInfo::get_extra_info.

§Safety
  • ptr must remain valid until DuckDB calls destroy, or for the lifetime of the database if destroy is None.
  • The pointee must be Send + Sync. DuckDB hands the same pointer to the cast callback on every thread that executes the cast, possibly at the same moment, and destroy runs on whichever thread releases the last reference — or, if the builder is dropped unregistered, on the thread that drops it (the builder is Send). Shared mutable state behind the pointer needs a Mutex or atomics.
Source

pub fn extra_info_typed<T: Send + Sync + 'static>(self, value: T) -> Self

Attaches value as this cast’s extra info: the safe, typed form of extra_info.

quack-rs boxes value behind a type tag and generates its destructor, which contains a panic in T::drop and runs once — when DuckDB releases the cast, or when this builder is dropped unregistered. Read it in the callback with CastFunctionInfo::extra_info_ref, which returns None for any other type instead of reinterpreting memory. T is Send + Sync because every thread running the cast reads the same value.

§Example
use quack_rs::cast::{CastFunctionBuilder, CastFunctionInfo};
use quack_rs::types::TypeId;

struct Unit(&'static str);

let builder =
    CastFunctionBuilder::new(TypeId::Double, TypeId::Varchar).extra_info_typed(Unit("kg"));

fn unit(info: &CastFunctionInfo) -> &str {
    // SAFETY: this cast's extra info is only ever set with `extra_info_typed`.
    unsafe { info.extra_info_ref::<Unit>() }.map_or("", |u| u.0)
}
Source

pub unsafe fn register( self, con: duckdb_connection, ) -> Result<(), ExtensionError>

Registers the cast function on the given connection.

§Errors

Returns ExtensionError if:

  • The function callback, source type or target type was not set.
  • The source or target type is a bare composite TypeId (DECIMAL, ENUM, LIST, STRUCT, MAP, ARRAY, UNION); build it as a LogicalType and use new_logical.
  • con is null.
  • The source or target type is, or contains, ANY or INVALID (DuckDB refuses these).
  • DuckDB reports a registration failure.
§extra_info ownership

Every failure above is detected in Rust before DuckDB is called, so the builder still owns any extra_info and frees it (exactly once) when it is dropped. duckdb_register_cast_function itself returns early for exactly those conditions before taking ownership, which is why they are checked here first. The one remaining failure — an exception inside DuckDB while installing the cast — is ambiguous (it may or may not have taken ownership already), so the allocation is left to DuckDB in that case: a possible leak, never a double free.

§Safety

con must be a valid, open duckdb_connection.

Trait Implementations§

Source§

impl Debug for CastFunctionBuilder

Source§

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

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

impl Send for CastFunctionBuilder

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.