pub struct ArrowSchema(/* private fields */);Expand description
An owned Arrow C Data Interface schema.
Released on drop, unless it was already released or moved out with
into_raw.
§Reading a released schema
The Arrow specification says that once release has run, every other field
of the record is undefined — DuckDB’s own release callback frees the block
that format, name and children point into. So format,
name and child all return None once
is_released is true, rather than handing out a
dangling pointer.
Implementations§
Source§impl ArrowSchema
impl ArrowSchema
Sourcepub const fn empty() -> Self
pub const fn empty() -> Self
An unfilled record, ready for a producer to write into.
release is null, so dropping one frees nothing.
Sourcepub const unsafe fn from_raw(raw: RawArrowSchema) -> Self
pub const unsafe fn from_raw(raw: RawArrowSchema) -> Self
Takes ownership of a filled ABI record.
§Safety
rawmust be a record whosereleasecallback this value may call exactly once, and no other wrapper may hold the same record.- It must be a valid Arrow C Data Interface schema:
formatandnamenull or NUL-terminated,childrennull or pointing atn_childrenvalid child schemas, recursively. The safe accessors (format,name,child) andschema_from_arrowread through those pointers.
Sourcepub const unsafe fn take_from(ptr: *mut RawArrowSchema) -> Self
pub const unsafe fn take_from(ptr: *mut RawArrowSchema) -> Self
Moves the record out of ptr, leaving a released placeholder behind.
This is how to import from another Arrow binding — arrow-rs’s
FFI_ArrowSchema, say — without a double free: the source is overwritten
with RawArrowSchema::empty, so its own destructor sees release == NULL and does nothing.
§Safety
ptrmust be valid for reads and writes and properly aligned forRawArrowSchema, which every Arrow C Data InterfaceArrowSchemais.- The caller must not use the record behind
ptrafterwards, other than to drop the (now released) wrapper holding it. - The record behind
ptrmust meetfrom_raw’s contract: this value calls itsreleasecallback, and the safe accessors read through its pointers.
Sourcepub fn into_raw(self) -> RawArrowSchema
pub fn into_raw(self) -> RawArrowSchema
Relinquishes ownership, returning the ABI record.
The caller becomes responsible for calling release on it.
Sourcepub const fn as_ptr(&self) -> *const RawArrowSchema
pub const fn as_ptr(&self) -> *const RawArrowSchema
A pointer to the ABI record, for C APIs that read it.
Sourcepub const fn as_mut_ptr(&mut self) -> *mut RawArrowSchema
pub const fn as_mut_ptr(&mut self) -> *mut RawArrowSchema
A mutable pointer to the ABI record, for C APIs that fill it.
Sourcepub const fn is_released(&self) -> bool
pub const fn is_released(&self) -> bool
Whether release is null — either never filled, or already released.
Sourcepub fn format(&self) -> Option<&str>
pub fn format(&self) -> Option<&str>
The Arrow format string, e.g. "+s" for the struct at the root of a
converted DuckDB schema.
None if the schema is released, the pointer is null, or the string is
not valid UTF-8.
Sourcepub fn child_count(&self) -> usize
pub fn child_count(&self) -> usize
Number of child schemas — the column count, at the root of a converted
DuckDB schema. 0 once released.
Sourcepub fn child(&self, index: usize) -> Option<&Self>
pub fn child(&self, index: usize) -> Option<&Self>
Borrows child schema index.
Children are owned by this schema’s producer and released with it, which
is why this borrows rather than handing out an ArrowSchema that would
try to release them again.