Trait Function 

pub trait Function:
    Send
    + Sync
    + 'static {
    // Required methods
    fn name(&self) -> &'static str;
    fn eval<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        ctx: &dyn FunctionContext<'b>,
    ) -> Result<CalcValue<'b>, ExcelError>;

    // Provided methods
    fn caps(&self) -> FnCaps { ... }
    fn namespace(&self) -> &'static str { ... }
    fn min_args(&self) -> usize { ... }
    fn variadic(&self) -> bool { ... }
    fn volatile(&self) -> bool { ... }
    fn arg_schema(&self) -> &'static [ArgSchema] { ... }
    fn aliases(&self) -> &'static [&'static str] { ... }
    fn dependency_contract(
        &self,
        _arity: usize,
    ) -> Option<FunctionDependencyContract> { ... }
    fn semantic_contract(
        &self,
        _arity: usize,
    ) -> Option<FunctionSemanticContract> { ... }
    fn function_salt(&self) -> u64 { ... }
    fn propagate_format(&self, result: &CalcValue<'_>) -> Option<FormatId> { ... }
    fn apply_format_propagation<'a>(
        &self,
        result: CalcValue<'a>,
    ) -> CalcValue<'a> { ... }
    fn eval_reference<'a, 'b, 'c>(
        &self,
        _args: &'c [ArgumentHandle<'a, 'b>],
        _ctx: &dyn FunctionContext<'b>,
    ) -> Option<Result<ReferenceType, ExcelError>> { ... }
    fn resolve_reference_or_value<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        ctx: &dyn FunctionContext<'b>,
        value_fallback: &dyn Fn() -> Result<CalcValue<'b>, ExcelError>,
    ) -> Result<FunctionResolution<'b>, ExcelError> { ... }
    fn dispatch<'a, 'b, 'c>(
        &self,
        args: &'c [ArgumentHandle<'a, 'b>],
        ctx: &dyn FunctionContext<'b>,
    ) -> Result<CalcValue<'b>, ExcelError> { ... }
}

Revised, object-safe trait for all Excel-style functions.

This trait uses a capability-based model (FnCaps) to declare function properties, enabling the evaluation engine to select the most optimal execution path (e.g., scalar, vectorized, parallel).

Required Methods

fn name(&self) -> &'static str

fn eval<'a, 'b, 'c>( &self, args: &'c [ArgumentHandle<'a, 'b>], ctx: &dyn FunctionContext<'b>, ) -> Result<CalcValue<'b>, ExcelError>

The unified evaluation path.

This method replaces the separate scalar, fold, and map paths. Functions use the provided ArgumentHandles to access inputs as either scalars or RangeViews (Arrow-backed virtual ranges).

Provided Methods

fn caps(&self) -> FnCaps

Capability flags for this function

fn namespace(&self) -> &'static str

fn min_args(&self) -> usize

fn variadic(&self) -> bool

fn volatile(&self) -> bool

fn arg_schema(&self) -> &'static [ArgSchema]

fn aliases(&self) -> &'static [&'static str]

Optional list of additional alias names (case-insensitive) that should resolve to this function. Default: empty slice. Implementors can override to expose legacy names. Returned slice must have ’static lifetime (typically a static array reference).

fn dependency_contract( &self, _arity: usize, ) -> Option<FunctionDependencyContract>

Optional dependency contract for passive planning/FormulaPlane analysis.

The default is deliberately conservative: functions that do not opt in must not receive dependency-summary optimization. Implementations should return Some only for arities and argument roles they can describe without under-approximating dependencies.

fn semantic_contract(&self, _arity: usize) -> Option<FunctionSemanticContract>

Explicit semantic classification for this call arity.

The public default is intentionally untrusted. The registry supplies a sealed default only for crate-owned builtin registration.

fn function_salt(&self) -> u64

fn propagate_format(&self, result: &CalcValue<'_>) -> Option<FormatId>

Derive an eval-internal scalar format annotation for this call. Functions drop annotations by default; selection and temporal constructors override it.

fn apply_format_propagation<'a>(&self, result: CalcValue<'a>) -> CalcValue<'a>

fn eval_reference<'a, 'b, 'c>( &self, _args: &'c [ArgumentHandle<'a, 'b>], _ctx: &dyn FunctionContext<'b>, ) -> Option<Result<ReferenceType, ExcelError>>

Optional reference result path. Only called by the interpreter/engine when the callsite expects a reference (e.g., range combinators, by-ref argument positions, or spill sources).

Default implementation returns None, indicating the function does not support returning references. Functions that set RETURNS_REFERENCE should override this.

fn resolve_reference_or_value<'a, 'b, 'c>( &self, args: &'c [ArgumentHandle<'a, 'b>], ctx: &dyn FunctionContext<'b>, value_fallback: &dyn Fn() -> Result<CalcValue<'b>, ExcelError>, ) -> Result<FunctionResolution<'b>, ExcelError>

Resolve a reference-capable function while preserving scalar-selector caching.

The fallback deliberately re-enters the caller’s ordinary value path. That preserves dispatch validation and array lifting for existing functions whose eval_reference declines a particular argument shape. Array-valued selectors may be evaluated once by each path.

fn dispatch<'a, 'b, 'c>( &self, args: &'c [ArgumentHandle<'a, 'b>], ctx: &dyn FunctionContext<'b>, ) -> Result<CalcValue<'b>, ExcelError>

Dispatch to the unified evaluation path with automatic argument validation.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors