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
impl Engine
Sourcepub fn sheet_names(&self) -> Vec<String>
pub fn sheet_names(&self) -> Vec<String>
The names of the sheets currently in the workbook, sorted.
Sourcepub fn get_value(&self, sheet: &str, row: u32, col: u32) -> Option<Value>
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.
Sourcepub fn volatile_cells(&self) -> Vec<CellId> ⓘ
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.
Sourcepub fn set_cell(
&mut self,
sheet: &str,
row: u32,
col: u32,
input: &str,
) -> Result<(), EngineError>
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 withformula-lang(sheet-qualified references supported; seecrate::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.
Sourcepub fn recalculate(&mut self) -> Result<(), EngineError>
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.
Sourcepub fn recalculate_incremental(
&mut self,
edited: &[(String, u32, u32)],
) -> Result<(), EngineError>
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.
Sourcepub fn to_xlsx(&self) -> Result<Vec<u8>, EngineError>
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.
Sourcepub fn from_xlsx(data: &[u8]) -> Result<Self, EngineError>
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.