Skip to main content

CastFunctionInfo

Struct CastFunctionInfo 

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

Ergonomic wrapper around the duckdb_function_info handle provided to a cast callback.

Exposes the cast-specific methods that are only meaningful inside a cast function callback.

Implementations§

Source§

impl CastFunctionInfo

Source

pub const EMPTY_ERROR_PLACEHOLDER: &'static str = "cast function reported an error without a message"

The message set_error and set_row_error report in place of an empty one.

Without it, DuckDB fails the query with Conversion Error: followed by nothing.

Source

pub const unsafe fn new(info: duckdb_function_info) -> Self

Wraps a raw duckdb_function_info provided by DuckDB inside a cast callback.

§Safety

info must be a valid duckdb_function_info passed by DuckDB to a cast callback.

Source

pub fn cast_mode(&self) -> CastMode

Returns whether this invocation is a TRY_CAST or a regular CAST.

Check this inside your callback to decide between aborting on error (CastMode::Normal) and producing NULL with a per-row error (CastMode::Try).

Source

pub unsafe fn get_extra_info(&self) -> *mut c_void

Retrieves the extra-info pointer previously set via CastFunctionBuilder::extra_info.

Returns a raw *mut c_void. Cast it back to your concrete type.

§Safety

The returned pointer is only valid as long as the cast function is registered and DuckDB has not yet called the destructor.

Source

pub unsafe fn extra_info_ref<T: 'static>(&self) -> Option<&T>

Borrows the extra info set with CastFunctionBuilder::extra_info_typed as a T; None when none was set or it holds another type.

§Safety

This cast’s extra info, if any, was set through extra_info_typed and not through the raw extra_info: the type tag read here is the one extra_info_typed writes, and a raw pointer carries none.

Source

pub fn set_error(&self, message: &str)

Records the error DuckDB raises when the callback returns false.

Use this only in CastMode::Normal, where returning false fails the query with this message as a Conversion Error. In CastMode::Try the message is kept but the query does not fail, and no row becomes NULL because of it: use set_row_error for every failed row instead.

An interior null byte in message is replaced by ?. An empty message is replaced by EMPTY_ERROR_PLACEHOLDER.

Source

pub unsafe fn set_row_error( &self, message: &str, row: idx_t, output: duckdb_vector, )

Reports a per-row conversion failure and sets row of output to NULL.

duckdb_cast_function_set_row_error does both: it records message as the cast’s error message and calls FlatVector::SetNull(output, row) (src/main/capi/cast_function-c.cpp). In CastMode::Try this is the only way a row becomes NULL; in CastMode::Normal the message is what the query fails with once the callback returns false.

An interior null byte in message is replaced by ?. An empty message is replaced by EMPTY_ERROR_PLACEHOLDER.

§Safety
  • output must be the same duckdb_vector passed to the cast callback.
  • row must be less than the count passed to the cast callback. DuckDB does not check it: the validity-mask bounds check is a D_ASSERT, compiled out of release builds (src/include/duckdb/common/types/validity_mask.hpp), so an out-of-range row writes past the end of the validity mask.

Trait Implementations§

Source§

impl Debug for CastFunctionInfo

Source§

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

Formats the value using the given formatter. 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.