Skip to main content

Engine

Struct Engine 

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

A spreadsheet calculation engine.

Named sheets of cells (sheet_core::Sheet), a workbook-level dependency graph (per-sheet sheet_core::DependencyGraph plus the engine’s cross-sheet edges), a cache of computed values, and the dirty set incremental recalculation drains. See the crate docs for the calculation model.

Implementations§

Source§

impl Engine

Source

pub fn new() -> Self

An empty workbook with no sheets. Sheets are created on demand by set_cell and by from_xlsx.

Source§

impl Engine

Source

pub fn sheet_names(&self) -> Vec<String>

The names of the sheets currently in the workbook, sorted.

Source

pub fn has_sheet(&self, sheet: &str) -> bool

true when the named sheet exists.

Source

pub fn get_value(&self, sheet: &str, row: u32, col: u32) -> Option<Value>

The cached value of one cell — the computed result for a formula, the literal for anything else. None for a blank cell, an unknown sheet, or a formula that has never been calculated.

Source

pub fn volatile_cells(&self) -> Vec<CellId> ⓘ

Every volatile cell (TODAY, NOW, OFFSET formulas), in (sheet, row, col) order. These re-evaluate on every calculation, full or incremental, Excel-style.

Source

pub fn set_cell( &mut self, sheet: &str, row: u32, col: u32, input: &str, ) -> Result<(), EngineError>

Sets one cell from user input.

Input grammar, Excel-flavored:

  • =… — a formula, parsed with formula-lang (sheet-qualified references supported; see crate::qualified);
  • a number — stored numeric ("42", "-3.5", "1e3");
  • TRUE / FALSE, any case — stored logical;
  • an error literal ("#DIV/0!" and the other canonical spellings) — stored as an error value;
  • anything else — stored text, verbatim.

The cell is marked dirty; nothing computes until recalculate or recalculate_incremental. A formula replacing a formula swaps the dependency edges; a literal replacing a formula removes them. Referencing a sheet that does not exist is legal at set time (spreadsheets let you type ahead) — such reads evaluate to #REF! until the sheet appears.

§Errors

EngineError::Formula when formula text does not parse; EngineError::Graph when its references cannot be modeled (for example a range wider than sheet_core::refs::RANGE_CELL_CAP). A rejected formula changes nothing except dropping the cell’s previous cached value.

Source

pub fn recalculate(&mut self) -> Result<(), EngineError>

Evaluates every formula in the workbook, in topological order — each formula after every formula it reads, across sheets. The dirty set is drained.

§Errors

EngineError::CircularReference when the workbook contains circular references. Everything not on a cycle has still been evaluated when the error is raised (Excel computes the rest of the workbook); cells on a cycle keep no value.

Source

pub fn recalculate_incremental( &mut self, edited: &[(String, u32, u32)], ) -> Result<(), EngineError>

Evaluates only what an edit made stale: the edited cells and their transitive dependents, plus every volatile cell — in topological order, so a chain settles in one pass.

edited lists cells that changed outside the engine’s bookkeeping (typically the cells of a set_cell batch); cells dirtied by earlier set_cell calls are included automatically, so recalculate_incremental(&[]) is the “recalculate what is pending” form.

On a large sheet whose edit touches a small subgraph this is proportionally cheaper than a full recalculate.

§Errors

EngineError::CircularReference when the pending set meets a cycle — same contract as recalculate.

Source

pub fn to_xlsx(&self) -> Result<Vec<u8>, EngineError>

Serializes the workbook to XLSX bytes. Formula cells carry their cached results, so a to_xlsx → from_xlsx round-trip preserves values without a recalculation.

§Errors

EngineError::Xlsx when the codec rejects the workbook.

Source

pub fn from_xlsx(data: &[u8]) -> Result<Self, EngineError>

Loads a workbook from XLSX bytes. Formula cells come back with their cached results (the file’s stored values); a recalculate refreshes them.

§Errors

EngineError::Xlsx when the bytes are not a readable workbook; EngineError::Formula / EngineError::Graph when a stored formula cannot be parsed or modeled; EngineError::DuplicateSheet for duplicated sheet names.

Trait Implementations§

Source§

impl Debug for Engine

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for Engine

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

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.