IronCalc Base

IronCalc Base is the calculation engine at the heart of the IronCalc project — an MIT/Apache-2.0 licensed spreadsheet stack written in Rust. It owns the model of a workbook (sheets, cells, styles, conditional formatting, merged cells) and the formula machinery that parses expressions, resolves references, and evaluates them into typed results, closely mirroring Excel’s function library and error semantics.

Because it’s a pure Rust crate with no UI or file-format code baked in, ironcalc_base is designed to be embedded: the sibling xlsx crate reads and writes .xlsx files against it, and WASM/Python/Node.js bindings expose the same engine to browsers and other language runtimes. Any Rust application that needs to evaluate spreadsheet-style formulas — from a backend service to a desktop app — can depend on it directly.

What You Get

• Model API - Model::new_empty plus set_user_input/get_cell_value_by_index/evaluate for building and calculating a workbook programmatically
• Formula parser and lexer - a custom expressions module that tokenizes and parses formula text into an AST, including array formulas and named ranges
• Excel-compatible function library - hundreds of built-in functions across math/trig, statistical, financial, text, logical, lookup-and-reference, date-and-time, engineering, database, and information categories
• Styling and formatting - cell styles, built-in style presets, themes, number formats, and conditional formatting evaluation
• UserModel layer - higher-level operations for UI-driven editing: undo/redo history, autofill, clipboard cut/paste, border editing, and merged-cell handling
• Locale and language support - configurable locale, language, and timezone per model, with a compiled locale database bundled into the crate
• WASM-ready - conditional compilation swaps in WASM-friendly dependencies (js-sys, wasm-bindgen, regex-lite) when targeting wasm32, which is how the browser and JS bindings reuse the same engine

Common Use Cases

• Embedding a calculation engine - a Rust backend service needs to evaluate user-supplied spreadsheet formulas without shelling out to Excel or a headless browser
• Building custom spreadsheet UIs - a desktop or web app (via the WASM bindings) wants full spreadsheet editing behavior — undo/redo, autofill, clipboard — without reimplementing formula evaluation
• Server-side formula validation - an application accepts formula strings from users and needs to parse, statically analyze, and evaluate them safely and deterministically
• Programmatic report generation - code builds a workbook cell-by-cell (as in the crate’s own examples), applies formulas, evaluates, and hands the result off to the sibling xlsx crate for export
• Cross-language spreadsheet tooling - a project wants one shared, tested formula engine reused from Rust, Python, and Node.js via the project’s bindings crates instead of maintaining separate implementations per language

Under The Hood

Architecture The crate centers on Model (in model.rs, ~4,000 lines), which owns the workbook’s worksheets, styles, locale/language/timezone settings, and drives the parse-evaluate cycle: formula strings go through a hand-written lexer and recursive-descent parser (expressions/lexer, expressions/parser) into an AST of Nodes, which the model then walks to produce a typed CalcResult. A separate UserModel layer (user_model/) wraps Model with UI-oriented operations — undo/redo history, autofill, clipboard, border editing, merged cells — so that a caller building an interactive spreadsheet doesn’t have to reimplement those semantics on top of the raw engine. Formatting concerns (number formats, date detection) live in their own formatter module, and conditional formatting and styles are modeled as data evaluated against cells rather than baked into rendering. The crate is UI- and file-format-agnostic by design: the sibling xlsx crate and the WASM/Python/Node bindings are the only consumers that touch file I/O or a runtime environment.

Tech Stack Pure Rust 2021 edition with a deliberately small non-WASM dependency set: serde for (de)serialization, chrono/chrono-tz for date and timezone handling, bitcode for compact binary encoding (used for the bundled locale database), csv, and statrs for statistical functions; rand and regex are pulled in only for non-WASM targets, while wasm-bindgen, js-sys, and regex-lite are swapped in under cfg(target_arch = "wasm32") so the same source compiles for the browser. The crate is one member of a Cargo workspace alongside the xlsx crate and bindings/wasm, bindings/python, and bindings/nodejs, all of which depend on this engine rather than duplicating logic.

Code Quality The repository carries an extensive Rust unit and integration test suite — hundreds of dedicated test files under src/test/, including a compatibility subdirectory that appears to check output against Excel-style expectations, plus per-function tests for date, financial, statistical, and lookup functions. CI (make lint) runs cargo fmt --check and cargo clippy with -W clippy::unwrap_used -W clippy::expect_used -W clippy::panic -D warnings, meaning panics and unwraps are actively discouraged outside test code, and #![deny(missing_docs)] is set on the core model.rs module to enforce documented public APIs. Coverage is tracked via grcov/Codecov, and multi-OS CI (Ubuntu and macOS) plus separate JS, Python, and Node.js test jobs exercise the bindings against the same engine.

API Design The public surface is intentionally small and object-oriented around Model: construct with Model::new_empty(name, locale, timezone, language), mutate cells with set_user_input(sheet, row, column, value), then call evaluate() and read results back with typed getters like get_cell_value_by_index. This mirrors how a developer already thinks about spreadsheets (sheet/row/column addressing, formula strings, typed cell values) rather than exposing internal AST or evaluator types, which keeps the crate’s own README examples to a handful of lines. Errors surface as idiomatic Result types rather than panics for user-facing operations, consistent with the clippy lint configuration.