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
cellXfsentries; 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 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§
- Sheet
Data - One worksheet: its name and sparse cell storage. Coordinates are 0-based
(row, col); iteration is row-major (deterministic) via theBTreeMap. - Xlsx
Cell - One cell: value, optional style index, optional formula text.
- Xlsx
Workbook - A parsed XLSX package: named sheets in workbook order, the shared-string table, and the style-table size.