Crate cellrune

Expand description

Bounded XLSX/XLSM reading, deterministic calculation, editing, and writing.

CellRune separates source data from recalculated results:

read_xlsx_path, read_xlsx_bytes, or read_xlsx creates an immutable WorkbookSnapshot.
calculate_workbook creates a separate owned CalculationSnapshot without changing the source workbook or its saved XLSX results.
Each formula result is either a typed CalculationCellResult::Value or a structured CalculationCellResult::Unavailable issue.

§Quick start

use cellrune::{
    CalculationCellResult, CalculationOptions, FiniteNumber, ReadOptions, calculate_workbook,
    read_xlsx_path,
};

let workbook = read_xlsx_path("input.xlsx", ReadOptions::default())?;

let options = CalculationOptions::default()
    .with_today_serial(FiniteNumber::new(46_225.0)?);
let calculation = calculate_workbook(&workbook, options);

if let Some(sheet) = workbook.sheet_by_name("Sheet1") {
    let source_cell = sheet.cell_by_a1("A1")?;
    let _ = source_cell;
}

for (cell, result) in calculation.cells() {
    match result {
        CalculationCellResult::Value(value) => println!("{cell:?}: {value:?}"),
        CalculationCellResult::Unavailable(issue) => {
            eprintln!("{cell:?}: {}", issue.code().as_str());
        }
    }
}

§Failure model

CellRune keeps failures at their owning boundary:

XlsxReadError means no trustworthy workbook snapshot could be produced. Its XlsxReadError::code is stable and machine-readable.
Diagnostic records a compatibility caveat on a successfully read workbook.
CalculationIssue explains why one formula has no recalculated value. Unsupported engine capabilities are not converted into Excel errors and cannot be hidden by IFERROR.
CellValue::Error represents an actual spreadsheet error value.
ValidationError rejects invalid caller-provided model values and addresses.

Reading never executes macros or follows external links. Calculation is explicit and does not mutate or implicitly write a workbook. Recalculated result materialization is a separate explicit operation on package-backed documents.

§Numeric contract

Calculated numbers are not guaranteed to be bit-identical to Excel’s. docs/NUMERICS.md records every known deliberate difference, the Excel build each statement was measured against, and which function families remain unmeasured. Compare results with a tolerance rather than for equality.

Two behaviors are selectable through CalculationOptions, and both default to matching Excel rather than to what releases up to 0.1.2 did:

ArithmeticSemantics decides whether Excel’s narrow near-zero correction is applied to a decimal/rational cancellation, or every IEEE-754 residue is preserved.
FinancialSolverSemantics decides whether IRR, XIRR, and RATE stop at the iteration budget Microsoft documents, or search longer and return values where Excel reports #NUM!.

Select ArithmeticSemantics::Ieee754 and FinancialSolverSemantics::ExtendedSearch to restore the 0.1.2 behavior.

Structs§

CalculationCellId: Stable identity of a formula cell within one workbook snapshot.
CalculationDelta: Bounded, deterministically ordered result changes from one installed calculation.
CalculationDeltaCell: One changed direct or materialized calculation result.
CalculationDeltaPage: One cursor page of complete, individually bounded calculation deltas.
CalculationHints: Calculation hints read from workbook metadata without triggering calculation.
CalculationIssue: A structured formula calculation issue with optional source-specific detail.
CalculationLimits: Resource limits applied while formulas are parsed, scheduled, and evaluated.
CalculationOptions: Deterministic inputs for volatile calculation behavior.
CalculationSnapshot: Immutable formula results, separate from source literals and saved XLSX values.
CalculationTarget: A rectangular set of requested cells on one sheet.
CancellationToken: Thread-safe cooperative cancellation signal for one bounded operation.
Cell: A sparse cell with a validated address and content.
CellAddress: A validated cell address ordered in row-major order.
CellPhonetics: Borrowed effective phonetic metadata for one cell.
CellRange: A non-empty rectangular range with validated, inclusive endpoints.
Column: A validated, one-based Excel column index.
ColumnPhoneticVisibility: One source column range carrying a default phonetic visibility flag.
CompletedCalculation: A calculated but not yet installed session result.
CompletedTargetCalculation: A partial result awaiting source-state validation, never a complete calculation snapshot.
CompletedWorkbookTransaction: A fully calculated transaction that can be inspected, installed once, or discarded.
DefinedName: A validated workbook or sheet-local name formula.
DefinedNameAnalysisError: Execution failure returned separately from a semantic analysis result.
DefinedNameAnalysisOptions: Bounded options for a defined-name inspection.
DefinedNameAnalysisOptionsError: Error returned when a defined-name analysis limit is zero.
DefinedNameExternalReference: Typed detail retained from an external-workbook reference node.
DefinedNameSheetSpan: Stable workbook-order identity of a continuous 3-D sheet span.
Diagnostic: A compatibility or capability diagnostic, separate from Excel values.
DiagnosticCode: A stable machine-readable diagnostic code.
DocumentPresentation: XLSX presentation metadata kept separate from calculation semantics.
EditBatch: An ordered collection of workbook changes committed atomically.
EditReceipt: Result of committing one atomic edit batch.
FiniteNumber: A finite IEEE-754 number accepted at the workbook boundary.
FormulaCapabilityEntry: Capability status for one formula cell.
FormulaCapabilityReport: Deterministically ordered capability report for all formula cells.
FormulaCell: A formula cell before recalculation.
FormulaText: Formula text normalized to the XLSX storage form without a leading =.
FrozenPane: A validated frozen-pane position expressed as fixed row and column counts.
FunctionCatalogEntry: One deterministic entry in the supported function catalog.
FunctionUsageEntry: Aggregated use of one normalized function name in a workbook.
FunctionUsageReport: Workbook-level function demand report for prioritizing compatibility work.
InputHash: A SHA-256 digest associated with an input.
MaterializedCalculationCell: One typed or unavailable result in the complete calculation materialization view.
NumberFormat: Number-format metadata attached to a cell while preserving its raw numeric value.
OpenOptions: Options for opening a package-backed writable workbook document.
OutputHash: A SHA-256 digest associated with verified output bytes.
PackageSummary: Safely discovered package parts before workbook values are interpreted.
PhoneticProperties: Display properties attached to a phonetic string item.
PhoneticRun: One phonetic string displayed over a range of literal base text.
PhoneticTextRange: A half-open range in zero-based UTF-16 code units over the base cell text.
PhoneticWriteOptions: Visibility and display properties used when authoring phonetic text.
PreparedCalculation: An immutable calculation job safe to execute outside a session lock.
PreparedEditBatch: An atomic workbook edit batch staged for guarded installation.
PreparedTargetCalculation: An immutable partial calculation job that owns its source snapshot.
PreparedWorkbookTransaction: An immutable off-lock job containing one captured base and validated edit candidate.
Provenance: Deterministic producer and input identity metadata.
ProviderIdentity: The component that produced a snapshot or calculation.
ReadLimits: Resource limits applied before workbook semantics are interpreted.
ReadOptions: Read behavior and resource budgets for XLSX input.
RecalculatedWorkbook: Verified in-memory XLSX or XLSM output and its write report.
RecalculationWriteOptions: Options for materializing a calculation into an existing XLSX or XLSM package.
ResolvedPhoneticRun: One phonetic run resolved into byte offsets over concrete base text.
Row: A validated, one-based Excel row index.
SavedResultIssue: Why a stored formula result could not be interpreted.
SessionError: Structured stateful-session error with a stable code and optional detail.
SessionLimits: Stateful-session resource limits independent of formula-kernel limits.
Sheet: A sparse, format-neutral worksheet.
SheetId: A validated, non-zero workbook-local sheet identifier.
SheetName: A validated sheet name with its original spelling preserved.
SourceId: An opaque identifier for a source unit such as a package part.
SourceLocation: A source-linked position with invariants enforced by dedicated constructors.
Table: An Excel table (ListObject) definition owned by its worksheet.
TableAutoFilter: Typed auto-filter metadata attached to one table.
TableColorFilter: A differential-format color filter.
TableColumn: One table column with the stable XLSX column identifier.
TableColumnId: A validated, non-zero identifier for one column within an Excel table.
TableColumnName: A validated table-column name for authoring operations.
TableCustomFilter: One comparison used by a custom table filter.
TableCustomFilters: Custom comparisons for one filter column.
TableDateGroupItem: One grouped calendar value selected by a table auto-filter.
TableDateTimeValue: A validated OOXML xsd:dateTime token with its source spelling retained.
TableDynamicFilter: A dynamic date or numeric filter.
TableFilterColumn: One zero-based column selector and its typed filtering rule.
TableFormula: A calculated-column or totals-row formula stored in a table definition.
TableIconFilter: An icon-set filter.
TableId: A validated, non-zero workbook-local Excel table identifier.
TableName: A table name with its original spelling preserved.
TableNumericValue: A validated OOXML double token with its source spelling retained.
TableSortCondition: One typed sort condition within a table sort state.
TableSortState: Sort metadata attached to a table or auto-filter definition.
TableStyleInfo: The style flags attached to one table.
TableTopFilter: A top/bottom count or percentage filter.
TableValueFilters: Literal and grouped-date selections for one filter column.
TargetCalculationError: A targeted-calculation request failed without changing workbook state.
TargetCalculationLimits: Request-wide limits independent of per-formula calculation limits.
TargetCalculationResult: Immutable values for explicitly requested cells, never a complete workbook calculation.
TransactionAffectedFormula: One formula in the bounded semantic impact report.
TransactionImpactPage: One complete item-bounded transaction detail page.
TransactionInstallResultChange: One exact result change that installation will append to calculation history.
TransactionIssueChange: One exact base-to-candidate calculation issue difference.
TransactionPageCursor: Opaque report-local cursor for one transaction detail section.
TransactionResultChange: One exact base-to-candidate materialized result change.
WorkbookCalculationSession: Stateful workbook editor and persistent calculation engine.
WorkbookDraft: An owned, mutable workbook editing session with monotonic semantic revisions.
WorkbookFingerprint: A versioned, history-independent digest of workbook semantics.
WorkbookSnapshot: An immutable workbook snapshot with deterministic sheet lookup and order.
WorkbookSource: Non-sensitive source metadata retained by the snapshot.
WorkbookTransactionReceipt: Exact edit and calculation receipts returned by a successful transaction install.
WorkbookTransactionReport: Complete bounded summary and pageable details for one calculated transaction.
WriteLimits: Resource budgets for XLSX package generation and verification.
WriteOptions: XLSX output behavior and resource budgets.
WriteProvenance: Exact calculation and source identity recorded for a completed workbook write.
WriteReport: Structured outcome of materializing a calculation into a preserved workbook package.
XlsxDocument: An immutable workbook snapshot paired with its exact preserved XLSX or XLSM package.
XlsxReadError: A source-linked XLSX read failure with a stable error code.
XlsxWriteError: A source-linked XLSX write failure with a stable error code.

Enums§

ApplyChangesError: Error boundary for atomic edit validation and state conflicts.
ArithmeticSemantics: How arithmetic treats Excel’s narrow near-zero cancellation case.
CalculationCellResult: Result of calculating one formula cell.
CalculationDecisionReason: Deterministic explanation for the selected calculation schedule.
CalculationExecutionMode: Actual schedule used by one installed calculation.
CalculationIssueCode: Stable machine-readable reason that a formula was not calculated.
CalculationMode: Workbook calculation mode metadata.
CalculationOptionsError: Invalid caller-provided calculation configuration.
CellContent: The mutually exclusive content stored at a sparse cell address.
CellValue: A literal or saved cell value.
DateSystem: Excel’s serial date epoch selection.
DefinedNameAnalysis: Typed analysis of one workbook or sheet-local defined name.
DefinedNameAnalysisErrorKind: Stable execution-failure category for a defined-name query.
DefinedNameAnalysisLimitKind: Resource unit enforced by defined-name analysis.
DefinedNameDynamicKind: Dynamic reference construct that determines a name’s reference shape at calculation time.
DefinedNameExternalTargetKind: Typed target category of an external-workbook reference.
DefinedNameInvalidReason: Reason a reachable defined-name formula is invalid against the immutable workbook snapshot.
DefinedNameReferenceArea: One area in an ordered non-rectangular defined-name reference.
DefinedNameScope: Visibility scope of a workbook defined name.
DefinedNameUnsupportedReason: Reason a valid formula cannot be represented as static reference geometry.
DiagnosticSeverity: Severity independent of Excel cell errors.
ExcelError: An error value stored by a spreadsheet cell.
FinancialSolverSemantics: How the iterative financial solvers decide they have failed.
FormulaCapability: Static grammar and function-surface capability for one formula.
FormulaDialect: The formula grammar stored in a workbook snapshot.
FormulaMetadata: Formula container metadata preserved independently of formula text.
FunctionSupport: Whether a function name found in a workbook is implemented by the current engine.
InstallDeltaBasisReason: Why the installed-calculation delta has a different comparison basis than the preview.
MaterializedResultOrigin: Why a calculated cell is present in the complete materialization view.
NumberFormatKind: Semantic category inferred from an XLSX number format without changing the stored value.
PhoneticAlignment: Horizontal alignment of phonetic text over its base text.
PhoneticType: Character conversion requested for displayed phonetic text.
ReadOptionsError: Invalid caller-provided reader configuration.
RecalculationMode: Caller-selected recalculation policy.
RecalculationWritePolicy: Policy for formulas that do not have a current materialized calculation result.
SavedResult: A formula’s stored result, kept distinct from a blank result.
SessionErrorCode: Stable machine-readable failure produced by a stateful calculation session.
SharedFormulaRole: Whether a shared formula cell defines or follows its group.
SheetVisibility: Sheet visibility as represented by SpreadsheetML.
TableCalendarType: Calendar systems accepted by OOXML table value filters.
TableCustomFilterOperator: Comparison operators accepted by a custom table filter.
TableDateTimeGrouping: Calendar granularity used by one grouped-date filter item.
TableDynamicFilterType: Dynamic filter categories defined by OOXML.
TableFilterCriteria: The typed filtering rule attached to one auto-filter column.
TableFilterItem: One value or grouped date selected by a table auto-filter.
TableIconSet: Built-in icon sets accepted by OOXML table filters and sorts.
TableSortBy: Value source used by an OOXML sort condition.
TableSortMethod: Sort collation method declared by OOXML.
TableType: The data source represented by an Excel table definition.
TargetCalculationErrorCode: Stable request failure for targeted calculation.
TotalsRowFunction: The totals-row aggregation declared for one table column.
TransactionDetailItem: One item from a transaction detail page.
TransactionDetailSection: A transaction report detail section.
TransactionImpactCause: Why one formula appears in the affected-formula section.
TransactionImpactCoverage: Completeness of the semantic affected-formula set.
TransactionIssueChangeKind: Classification of one exact calculation issue difference.
ValidationError: A violation of a format-neutral workbook invariant.
ValidationErrorCode: Stable machine-readable code for a format-neutral validation failure.
WorkbookChange: One validated workbook mutation in an atomic EditBatch.
WorkbookSourceKind: The caller-facing input adapter that supplied workbook bytes.
WriteOptionsError: Invalid caller-provided writer configuration.
XlsxDocumentKind: Open XML spreadsheet package kind retained by a writable document.
XlsxErrorCode: Stable machine-readable failure codes for XLSX file errors.
XlsxWriteErrorCode: Stable machine-readable failure codes for XLSX writing.

Constants§

EXCEL_MAX_COLUMNS: Maximum column supported by an Excel worksheet.
EXCEL_MAX_ROWS: Maximum row supported by an Excel worksheet.

Functions§

analyze_defined_name: Analyzes one defined name with default bounded options.
analyze_defined_name_cancellable: Analyzes one defined name with explicit options and cooperative cancellation.
analyze_defined_name_with_options: Analyzes one defined name with explicit bounded options.
calculate_targets: Calculates requested cells and their required precedents without changing the source.
calculate_workbook: Calculates formulas without mutating the source snapshot and records runtime issues per cell.
inspect_package: Validates package budgets and discovers workbook-related parts without reading cells.
open_xlsx_document: Opens a bounded package-backed workbook from a seekable reader.
open_xlsx_document_bytes: Opens a bounded package-backed workbook from in-memory XLSX or XLSM bytes.
open_xlsx_document_path: Opens a bounded package-backed workbook from a filesystem path without retaining the host path.
read_xlsx: Reads workbook metadata, sparse literal cells, formulas, and saved results from a bounded XLSX stream.
read_xlsx_bytes: Reads workbook metadata, sparse cells, formulas, and saved results from in-memory XLSX bytes.
read_xlsx_path: Opens and reads an XLSX workbook from a filesystem path without retaining the host path.
scan_formula_capabilities: Scans formula grammar and function-surface support without returning calculated values.
scan_formula_capabilities_with_options: Scans formula support under caller-provided deterministic parse, name, and dependency limits.
scan_function_usage: Counts normalized function demand using default calculation limits.
scan_function_usage_with_options: Counts normalized function demand using caller-provided calculation limits.
supported_function_catalog: Returns the deterministic catalog of function names implemented by this build.
write_preserved_xlsx_bytes: Rebuilds an opened package by raw-copying every unchanged ZIP entry.
write_recalculated_xlsx: Writes a fully prepared and verified recalculated package to an output.
write_recalculated_xlsx_bytes: Materializes a calculation, verifies the completed package, and returns owned archive bytes.
write_recalculated_xlsx_path: Saves a verified recalculated package to a new path or explicitly replaces the destination.
write_xlsx_draft: Writes a fully prepared draft archive to an output sink.
write_xlsx_draft_bytes: Calculates materialization output for a draft and returns a verified XLSX or XLSM archive.
write_xlsx_draft_path: Saves a verified draft package to a new path or explicitly replaces the destination.

Crate cellrune

Crate cellrune Copy item path

§Quick start

§Failure model

§Numeric contract

Structs§

Enums§

Constants§

Functions§

Crate cellrune