Skip to main content

Crate sheet_xlsx

Crate sheet_xlsx 

Source
Expand description

XLSX codec — workbook, worksheets, shared strings, styles, calc chain — parse and serialize.

sheet-xlsx reads and writes SpreadsheetML packages (.xlsx) on top of the estate’s [sheet-core] data model: XlsxWorkbook is the package view (named sheets, shared-string table, style count), and every cell coordinate is (row, col) in the shared 0-based space, with A1 conversion borrowed from sheet_core::refs.

§Package layout

A workbook is a ZIP of XML parts. On write, sheet-xlsx emits the canonical minimal set — [Content_Types].xml, _rels/.rels, xl/workbook.xml, its relationships, one xl/worksheets/sheetN.xml per sheet, xl/sharedStrings.xml, xl/styles.xml, and xl/calcChain.xml when any cell carries a formula. On read, parts are located through the relationship graph (not by hardcoded paths), so renamed or relocated packages still parse.

§Faithfulness over cleverness

The codec is deliberately lossless for the model it defines: round-tripping a workbook through write_xlsx → read_xlsx reproduces XlsxCell values exactly — including the choice between shared and inline strings, error literals, cached formula results, and style indices — which is the property the test suite checks on random workbooks. Full OOXML (charts, pivot tables, themes, merged cells, number formats) is out of scope: only the parts listed above are consumed or emitted, and the reader ignores everything else.

§Known v0.1 limitations (documented, typed, non-panicking)

  • Style definitions are not modeled. Styles are a count of cellXfs entries; indices survive round-trips, but fonts/fills/borders do not.
  • Shared formulas: the master cell keeps its formula text; slave cells keep their cached values but their translated formulas are not reconstructed.
  • Cells with neither value nor formula (e.g. style-only cells) are dropped — absence is blank, matching sheet-core.

§Layer

L1 substrate: depends on [sheet-core] (L1, same layer) plus zip and quick-xml; #![forbid(unsafe_code)].

§Example

use sheet_xlsx::{read_xlsx, write_xlsx, XlsxCell, SheetData, XlsxValue, XlsxWorkbook};
use std::collections::BTreeMap;

let mut cells = BTreeMap::new();
cells.insert((0, 0), XlsxCell { value: XlsxValue::Number(41.0), style_index: None, formula: None });
cells.insert((1, 0), XlsxCell {
    value: XlsxValue::FormulaString(String::new()),
    style_index: None,
    formula: Some(String::from("=A1+1")),
});

let mut wb = XlsxWorkbook::default();
wb.sheets.push(SheetData { name: String::from("Sheet1"), cells });

let bytes = write_xlsx(&wb).unwrap();
let round = read_xlsx(&bytes).unwrap();
assert_eq!(round.sheets.len(), 1);
assert_eq!(round.sheets[0].cells.get(&(1, 0)).unwrap().formula.as_deref(), Some("=A1+1"));

Re-exports§

pub use calc_chain::CalcChain;
pub use calc_chain::CalcEntry;
pub use error::XlsxError;
pub use reader::read_xlsx;
pub use shared_strings::SharedStrings;
pub use styles::Styles;
pub use writer::write_xlsx;

Modules§

calc_chain
The calc chain — xl/calcChain.xml.
error
Typed, exhaustive error taxonomy for the XLSX codec.
reader
Package reading — read_xlsx.
shared_strings
The shared-string table.
styles
Style-table metadata.
writer
Package writing — write_xlsx.

Structs§

SheetData
One worksheet: its name and sparse cell storage. Coordinates are 0-based (row, col); iteration is row-major (deterministic) via the BTreeMap.
XlsxCell
One cell: value, optional style index, optional formula text.
XlsxWorkbook
A parsed XLSX package: named sheets in workbook order, the shared-string table, and the style-table size.

Enums§

XlsxValue
The value of an XlsxCell, mirroring SpreadsheetML’s cell types.