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
impl CastFunctionInfo
Sourcepub const EMPTY_ERROR_PLACEHOLDER: &'static str = "cast function reported an error without a message"
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.
Sourcepub const unsafe fn new(info: duckdb_function_info) -> Self
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.
Sourcepub fn cast_mode(&self) -> CastMode
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).
Sourcepub unsafe fn get_extra_info(&self) -> *mut c_void
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.
Sourcepub unsafe fn extra_info_ref<T: 'static>(&self) -> Option<&T>
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.
Sourcepub fn set_error(&self, message: &str)
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.
Sourcepub unsafe fn set_row_error(
&self,
message: &str,
row: idx_t,
output: duckdb_vector,
)
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
outputmust be the sameduckdb_vectorpassed to the cast callback.rowmust be less than thecountpassed to the cast callback.DuckDBdoes not check it: the validity-mask bounds check is aD_ASSERT, compiled out of release builds (src/include/duckdb/common/types/validity_mask.hpp), so an out-of-rangerowwrites past the end of the validity mask.