Crate truecalc_workbook 

Workbook layer for the truecalc spreadsheet engine: engine-locked workbook, worksheet, and cell value types with a canonical JSON serialization contract.

Quick start

use truecalc_workbook::{Address, CellInput, EngineFlavor, RecalcContext, Value, Workbook, Worksheet};

// 1. Create a workbook locked to Google Sheets semantics.
let mut wb = Workbook::new(EngineFlavor::Sheets);

// 2. Add a sheet and write some cells.
wb.add_sheet(Worksheet::new("Budget")).unwrap();
let a1 = Address::from_a1("A1").unwrap();
let a2 = Address::from_a1("A2").unwrap();
let a3 = Address::from_a1("A3").unwrap();
wb.set("Budget", a1, CellInput::Literal(Value::Number(1000.0))).unwrap();
wb.set("Budget", a2, CellInput::Literal(Value::Number(500.0))).unwrap();
wb.set("Budget", a3, CellInput::Formula("=SUM(A1:A2)".to_string())).unwrap();

// 3. Recalculate to evaluate all formulas.
// timestamp_ms = Unix epoch in ms, tz = IANA timezone id, rng_seed = 0
let ctx = RecalcContext::new(1_780_000_000_000, "Etc/GMT", 0).unwrap();
let _changes = wb.recalc(&ctx);
assert_eq!(wb.get("Budget", a3).unwrap().value(), &Value::Number(1500.0));

Core concepts

• Workbook is a value object: Clone + PartialEq + Hash, no hidden state or callbacks. Mutate with Workbook::set / Workbook::clear and then drive recalc with Workbook::recalc or Workbook::recalc_incremental.

• Engine flavor (EngineFlavor) is required at creation (Workbook::new) and immutable for the workbook’s lifetime. It controls formula semantics and the date serial system.

• RecalcContext pins volatile functions (NOW, TODAY) to a fixed UTC instant + IANA timezone. Same workbook + same context ⇒ byte-identical recomputed grid.

• CellInput is the discriminated input type for Workbook::set: CellInput::Literal(value) or CellInput::Formula("=...".to_string()). Formula syntax is validated against the locked engine on set.

Serialization

Workbook::to_json / Workbook::from_json implement the canonical (RFC 8785 / JCS) serialization boundary — the byte-identical cross-surface contract used across Rust, WASM, MCP, and REST surfaces.

Related crates

• truecalc-core: the formula parser and evaluator; the Engine type and all formula evaluation lives there.

Modules

limits

Resource limits — the single source of truth for the structural caps of the scope ADR (2026-06-07-workbook-v1-scope.md, Decision 5).

Structs

Address

A parsed, in-bounds A1 address: 1-based (row, column).

Cell

An authored cell: a literal (value only) or a formula (formula + value). Schema spec §4.

CellRef

A fully resolved cell coordinate: a sheet (by its position-independent, case-folded name) and an in-bounds Address.

Change

One cell whose evaluated value a recalc changed.

DependencyGraph

The dependency graph of a Workbook: precedents and reverse-edge indexes derived from every formula cell via extract_refs.

NamedRange

A workbook-scoped named range (schema spec §7).

RangeRef

A resolved rectangular range: a sheet (folded name) and an inclusive, top-left-first corner pair.

RecalcContext

The deterministic context a recalc evaluates against (scope ADR Decision 3).

Resolved

The effective value at an address after spill resolution (schema spec §5), returned by Workbook::resolved.

SpillRect

An in-bounds spill rectangle: the geometry of one anchor’s reconstructed array. Cheap to copy; membership and indexing are O(1).

Workbook

An engine-locked spreadsheet workbook — a pure value object (no hidden state, no callbacks). Schema spec §2.

Worksheet

A named sheet holding a sparse cell grid (schema spec §3).

Enums

CellInput

What a Workbook::set writes into a cell: a literal value or a formula.

EngineFlavor

Which spreadsheet product’s semantics the engine targets.

Precedent

One resolved precedent of a formula cell: what a single Ref in the formula points at, after sheet/name resolution.

Value

An evaluated cell value — one of the seven types of schema spec §6.

WorkbookError

Errors from workbook value-type constructors and from Workbook::from_json / Workbook::to_json.

Constants

BLOCKED_SPILL_ERROR

The Sheets blocked-spill error code (schema spec §12 edge-case 1: Sheets reports a blocked array expansion as #REF!).

CIRCULAR_ERROR

The error a cell on (or downstream of) a circular dependency takes.

SCHEMA_VERSION

The schema version this library writes (schema spec §10). A string, not an integer: compared by exact match, never numerically.