Conversion reference

This chapter summarizes the built-in worksheet conversion surface. The behavioral chapters remain authoritative for design guidance; generated rustdoc remains authoritative for exact method signatures.

Input conversions

An Excel error supplied where another type is expected is propagated as that Excel error. Ordinary conversions do not ask Excel to coerce strings, booleans, references, or arrays into unrelated types.

When the return type is a formula-owned handle, input conversion also selects the formula-revision mode. Built-in values record semantic identities after conversion. A custom T: FromExcel<'call> must additionally implement ExcelInputIdentity; otherwise it is valid for ordinary UDFs but rejected for the handle-producing path. This keeps memoization tied to the Rust value the UDF can observe instead of to incidental Excel storage details.

Reference conversions

A parameter marked #[excel_arg(reference)] uses FromExcelReference<'call>, not FromExcel.

The built-in ExcelReference<'call> preserves:

• same-sheet or sheet-qualified identity;
• one or more rectangular areas;
• zero-based row and column bounds;
• a lifetime tied to the active Excel call.

Reference parameters require macro-sheet capability and are unavailable to async functions. They are raw call-scoped capabilities rather than ordinary formula-revision inputs. Copy only bounded metadata out of the borrowed value. Use the main-thread reference APIs to coerce or inspect cells when required.

Scalar output conversions

The following are direct scalar returns:

• f64, bool, i32, and exactly representable i64;
• String and &str;
• ExcelErrorValue;
• ExcelSerialDate;
• ExcelCellOutput and custom IntoExcel implementations;
• a type deriving ExcelEnum;
• RtdValue.

Matrix<T>, Row<T>, and Column<T> are owned array returns when every element implements IntoExcel. With the explicit unstable-output crate feature, xlfn::unstable::output::XlArrayBuilder::new produces XlArrayOutput directly in the final XLOPER12 cell buffer, avoiding an intermediate cell vector and a cell-buffer copy.

Result<T, E> is supported whenever T is supported for the selected execution mode and E: IntoXllError. The wrapper converts the error exactly once at the Excel boundary.

Execution-mode return matrix

“Volatile” is an additional marker, not an execution thread. A volatile thread-safe function, for example, needs both ThreadSafeReturn and VolatileReturn.

Presence behavior

Excel distinguishes:

• value: a normal scalar, array, error, or reference;
• blank: an empty cell (xltypeNil);
• missing: an omitted trailing argument (xltypeMissing).

Choose among:

• Option<T> when blank and missing are intentionally equivalent;
• OptionalExcelValue<T> when the distinction matters;
• #[excel_arg(blank = ..., missing = ..., default = ...)] when presence policy belongs in the worksheet signature;
• a required T when neither state is valid.

See Optional arguments and enums.

Arrays and allocation limits

XlArrayRef is the allocation-free mixed-value input path. It validates every cell’s type tag when the array is admitted, then exposes shape, indexed access, and lazy payload conversion through XlValueRef; XlStrRef borrows a string’s UTF-16 units until decoding is actually requested. Admission is linear in the cell count even if only a subset is read. Use XlArrayRef when lazy cell conversion is enough. Use &str, ExcelCellRef, or MatrixRef<T> when a synchronous function needs typed call-local values; MatrixRef materializes its Copy elements in call scratch. Use String, ExcelCellValue, Matrix<T>, or Vec<T> when the input must be owned, especially for async work.

Borrowed strings and grids use one CallScope scratch root. String decoding allocates UTF-8 bytes there, and borrowed matrix elements are stored there only when T: Copy; no destructor-bearing collection is placed in call scratch. The scope is dropped after the generated synchronous call returns.

Matrix::new and XlArrayBuilder::new require non-zero dimensions, checked multiplication, matching element count, and values within both Excel and framework limits.

Validate application-specific limits before allocating. Framework checks are host-protection ceilings, not a recommendation to return multi-million-cell arrays routinely.

Dynamic value variants

ExcelCellValue represents:

Number | Boolean | String | Error | Blank

ExcelValue represents:

Scalar(ExcelCellValue) | Missing | Array(Matrix<ExcelCellValue>)

Missing is an omitted argument and cannot occur inside an array. Blank is an empty cell and can occur as a scalar or array cell. The raw xltypeInt transport form is canonicalized to Number; it is not an input semantic variant. ExcelCellOutput intentionally has no blank or missing variant. Return ExcelErrorValue(ExcelError::NotAvailable) or an explicit ExcelCellOutput::Error when an unavailable result is intended.

Custom conversion checklist

For FromExcel<'call> and the built-in borrowed parameter views:

1. inspect only the active XlValueRef<'_>;
2. copy owned data before returning;
3. use the supplied static argument name in XllError::Input;
4. reject unsupported coercions and non-finite values explicitly;
5. bound all allocation from workbook-controlled lengths.
6. keep owned conversion independent of framework runtime state; do not retain temporary Excel pointers or call-scoped views in an owned result.

For IntoExcel:

1. validate the application value before allocation;
2. do not call Excel from thread-safe or async conversion paths;
3. preserve ownership until Excel calls xlAutoFree12 through framework-managed return storage.

See Custom conversions.