Skip to main content

ExcelReturn

Struct ExcelReturn 

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

Opaque local owner of one stable Excel ABI return tree.

Dropping this value while it is local releases the root and every nested backing allocation through ordinary Rust field drops. Consuming handoff leaves no Rust owner behind; Excel must then invoke the matching callback exactly once.

The root is deliberately read-only:

ⓘ
use excel_api::ExcelReturn;
fn cannot_mutate(mut value: ExcelReturn) {
    value.as_xloper().xltype = 0;
}

Handoff consumes the owner, so safe code cannot hand it off twice:

ⓘ
fn cannot_handoff_twice(value: excel_api::ExcelReturn) {
    let _first = value.into_raw_for_excel();
    let _second = value.into_raw_for_excel();
}

Raw reclamation is not a safe ownership constructor:

ⓘ
fn cannot_reclaim_safely(pointer: *mut excel_api_sys::XLOPER12) {
    excel_api::xl_auto_free12(pointer);
}

Implementations§

Source§

impl ExcelReturn

Source

pub fn from_plan(plan: ReturnPlan) -> Result<Self, ReturnMaterializationError>

Materializes pointer-free planning data into one locally owned ABI tree.

The result is still Rust-owned until Self::into_raw_for_excel consumes it; this does not create an Excel-owned xlFree result.

Source

pub fn as_xloper(&self) -> &XLOPER12

Read-only access to the stable root for inspection and future handoff.

Source

pub fn into_raw_for_excel(self) -> *mut XLOPER12

Consumes this local owner and transfers its complete allocation to Excel.

The returned pointer is the root at byte offset zero of the same ReturnAllocation; it is not a copy. Only the root receives xlbitDLLFree. Every nested value retains base type bits only and its storage remains owned by the leaked top-level allocation until the matching xl_auto_free12 call.

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 = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

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.