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
impl ExcelReturn
Sourcepub fn from_plan(plan: ReturnPlan) -> Result<Self, ReturnMaterializationError>
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.
Sourcepub fn as_xloper(&self) -> &XLOPER12
pub fn as_xloper(&self) -> &XLOPER12
Read-only access to the stable root for inspection and future handoff.
Sourcepub fn into_raw_for_excel(self) -> *mut XLOPER12
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.