sheet_core/lib.rs
1//! Spreadsheet data model — sparse cell storage, dependency DAG, topological
2//! evaluation order, formula reference extraction.
3//!
4//! `sheet-core` is the estate's spreadsheet substrate: it models a worksheet
5//! as a sparse `(row, col) → Cell` map and a worksheet's formulas as a
6//! dependency graph with deterministic evaluation order. It knows nothing
7//! about file formats — the XLSX codec lives in `sheet-xlsx` (L1, depends on
8//! this crate).
9//!
10//! # Sparse storage
11//!
12//! A [`Sheet`] is a [`BTreeMap`] of coordinates to [`Cell`]s — absent
13//! coordinates *are* the blank cells, so a million-row sheet with ten filled
14//! cells costs ten entries. Coordinates are 0-based `(u32, u32)` internally;
15//! [`refs`] converts to and from the `A1` notation users see.
16//!
17//! # Dependencies ([`DependencyGraph`])
18//!
19//! Formulas reference other cells (`=A1+B2`, `=SUM(A1:A9)`). The graph keeps
20//! both directions — [`precedents`](DependencyGraph::precedents) (what a
21//! formula reads) and [`dependents`](DependencyGraph::dependents) (what must
22//! recompute when a cell changes) — and derives:
23//!
24//! - [`topological_order`](DependencyGraph::topological_order): a total,
25//! deterministic order in which every formula is evaluated after every
26//! formula it reads,
27//! - [`dirty_subgraph`](DependencyGraph::dirty_subgraph): the minimal
28//! transitive recompute set for an edit, already in evaluation order,
29//! - [`has_circular`](DependencyGraph::has_circular): the circular
30//! references, reported as explicit cycles instead of silently looping.
31//!
32//! # Reference extraction ([`refs`])
33//!
34//! [`DependencyGraph`] parses formulas with the built-in extractor in
35//! [`refs`]: a lenient `A1`/`$A$1`/range/`Sheet!A1` scanner that walks the
36//! formula once and collects cell references, skipping string literals,
37//! function names, numbers, and everything it does not recognize. It is
38//! deliberately *not* a full formula parser — it extracts exactly the edges
39//! the dependency graph needs, and it is total: malformed input is a typed
40//! [`GraphError`], never a panic.
41//!
42//! # Layer
43//!
44//! L1 substrate: **zero dependencies** (not even optional ones),
45//! `no_std` + `alloc`, `#![forbid(unsafe_code)]`.
46//!
47//! # Example
48//!
49//! ```
50//! use sheet_core::{Cell, CellValue, DependencyGraph, Sheet};
51//!
52//! # fn main() -> Result<(), sheet_core::GraphError> {
53//! // Sparse storage: coordinates are 0-based, absence is blank.
54//! let mut sheet = Sheet::new();
55//! sheet.set(0, 0, Cell::number(41.0));
56//! sheet.set(1, 0, Cell::formula("=A1+1"));
57//! assert!(matches!(sheet.get(0, 0), Some(Cell { value: CellValue::Number(n), .. }) if *n == 41.0));
58//!
59//! // Dependencies: B2 reads A1, so A1's edit dirties B2.
60//! let mut graph = DependencyGraph::new();
61//! graph.add_formula((1, 0), "=A1+1")?;
62//! assert_eq!(graph.precedents((1, 0)), vec![(0, 0)]);
63//! assert_eq!(graph.dirty_subgraph(&[(0, 0)]), vec![(1, 0)]);
64//! assert!(graph.has_circular().is_empty());
65//! # Ok(())
66//! # }
67//! ```
68
69#![no_std]
70#![forbid(unsafe_code)]
71
72extern crate alloc;
73
74pub mod cell;
75pub mod error;
76pub mod graph;
77pub mod refs;
78pub mod sheet;
79
80pub use cell::{Cell, CellValue, ExcelError};
81pub use error::GraphError;
82pub use graph::DependencyGraph;
83pub use sheet::Sheet;