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
impl CastFunctionBuilder
Sourcepub const fn new(source: TypeId, target: TypeId) -> Self
pub const fn new(source: TypeId, target: TypeId) -> Self
Creates a new builder that will cast source values into target values.
Sourcepub fn new_logical(source: LogicalType, target: LogicalType) -> Self
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.
Sourcepub const fn source(&self) -> Option<TypeId>
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.
Sourcepub const fn target(&self) -> Option<TypeId>
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.
Sourcepub const fn implicit_cost(self, cost: i64) -> Self
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.
Sourcepub unsafe fn extra_info(
self,
ptr: *mut c_void,
destroy: duckdb_delete_callback_t,
) -> Self
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
ptrmust remain valid untilDuckDBcallsdestroy, or for the lifetime of the database ifdestroyisNone.- The pointee must be
Send + Sync.DuckDBhands the same pointer to the cast callback on every thread that executes the cast, possibly at the same moment, anddestroyruns on whichever thread releases the last reference — or, if the builder is dropped unregistered, on the thread that drops it (the builder isSend). Shared mutable state behind the pointer needs aMutexor atomics.
Sourcepub fn extra_info_typed<T: Send + Sync + 'static>(self, value: T) -> Self
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)
}Sourcepub unsafe fn register(
self,
con: duckdb_connection,
) -> Result<(), ExtensionError>
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 aLogicalTypeand usenew_logical. conis null.- The source or target type is, or contains,
ANYorINVALID(DuckDBrefuses these). DuckDBreports 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.