Crate rxls

Expand description

rxls — a native Rust spreadsheet library: no JVM, no Apache POI, no subprocess.

Reads legacy .xls (BIFF8 & BIFF5/7 — [MS-XLS]), .xlsx (SpreadsheetML), .xlsb (BIFF12), and .ods (OpenDocument); writes .xlsx. It surfaces typed cells (Cell) — number, date, boolean, error, text, and formula (the source is decompiled where supported, alongside the cached value).

Legacy .xls is an OLE2/CFB compound file whose Workbook stream is a sequence of BIFF records; the OOXML/ODF formats are ZIP packages of XML (binary records for .xlsb). The reader walks the shared-string table and the cell records of each worksheet.

Two ways to consume a file: plain text for search/indexing, or typed cells (Cell) for structured reading.

// Text:
let bytes = std::fs::read("book.xls").unwrap();
println!("{}", rxls::extract_text(&bytes).unwrap());

// Typed cells:
let wb = rxls::Workbook::open(&bytes).unwrap();
for sheet in &wb.sheets {
    for (row, col, cell) in sheet.cells() {
        match cell {
            rxls::Cell::Number(n)      => println!("{row},{col} = {n}"),
            rxls::Cell::Date(serial)   => println!("{row},{col} = serial {serial}"),
            rxls::Cell::Text(t)        => println!("{row},{col} = {t}"),
            _ => {}
        }
    }
}

For modern files (BIFF8) strings are UTF-16. For older BIFF5/7 files strings are 8-bit in the workbook’s ANSI codepage (announced by the CODEPAGE record); rxls decodes those correctly — e.g. Korean cp949 — via encoding_rs. Use Workbook::open_with_codepage to force a codepage. Date/time serials and percentages are rendered as Excel displays them (2024-03-15, 50%) via the XF / FORMAT / DATEMODE records. The parser is panic-free / bounds-checked: malformed input yields Error, never a crash. Authoring (.xlsx, default feature) covers styles, merges, formulas, data validation, conditional formatting, images, charts, tables, rich strings, comments, defined names, and document properties — see Workbook::to_xlsx.

Modules§

wasm: Portable read-only adapter used by WebAssembly consumers.

Structs§

Alignment: Cell text alignment.
Border: Cell borders (per edge).
CellProtection: Cell-level protection flags in an authored cell style.
CellStyle: Inline cell style for authoring. All None/default ⇒ Excel “General”; the writer interns these into the workbook’s deduped style tables.
Chart: A chart anchored to a cell box, plotting one or more data series from worksheet ranges. Used for authoring and populated by readers that surface chart metadata.
Color: An RGB color, emitted as an 8-hex ARGB string (FF + RRGGBB).
Comment: A legacy cell comment / note (authoring) — the yellow pop-up note anchored to a cell, emitted as xl/comments{N}.xml plus a VML shape.
CondFormat: A conditional-formatting rule applied to a cell range (authoring).
DataValidation: A data validation rule (authoring) — a dropdown list or a numeric/date/text constraint applied to a cell range.
Dimensions: Inclusive rectangular worksheet dimensions.
DocProperties: Workbook document properties (Dublin Core + extended), read from OOXML docProps/*, ODF meta.xml, and legacy OLE property streams, and written to docProps/core.xml and docProps/app.xml for .xlsx. Every field is optional; only the set ones are emitted.
ExcelDateTime: Calendar date/time decoded from an Excel serial number.
Fill: Cell fill formatting.
Font: A cell font.
Format: Writer format object, compatible with the existing CellStyle model.
FormulaRange: A rectangular view over cells that contain formula source text.
FormulaRangeRow: A borrowed row view inside a FormulaRange.
FormulaRangeRowCells: Iterator over one borrowed FormulaRangeRow’s formulas.
FormulaRangeRows: Iterator over borrowed FormulaRangeRow views.
Image: An embedded image (authoring). The bytes are stored as-is (no decoding); the image is anchored to a cell box and scaled to fit it.
PageSetup: Print / page setup for a worksheet (authoring). All fields optional; an unset field uses Excel’s default.
Picture: Workbook-level embedded picture metadata for calamine-style read facades.
ProtectionOptions: Granular worksheet-protection allowances (authoring). Each field, when true, permits the corresponding action even while the sheet is protected; the Default (all false) locks everything, matching Sheet::protect. Pass to Sheet::protect_with.
Range: A rectangular, calamine-style view over a worksheet’s effective cells.
RangeDeserializer: Iterator returned by RangeDeserializerBuilder.
RangeDeserializerBuilder: Builds a typed row deserializer for a Range.
RangeRow: A borrowed row view inside a Range.
RangeRowCells: Iterator over one borrowed RangeRow’s cells.
RangeRows: Iterator over borrowed RangeRow views.
Series: One chart data series. Ranges are A1 references into a sheet, e.g. Sheet1!$B$2:$B$9.
Sheet: One worksheet: a name, its non-empty cells, and layout/structure (authoring).
SheetMetadata: Public workbook sheet metadata.
SheetView: Public worksheet view metadata.
Sparkline: A sparkline (authoring): an in-cell mini chart that summarizes a source range. The range is an A1 reference such as Sheet1!$A$1:$A$12; location is the destination cell.
Spreadsheet: A workbook plus the original package bytes needed for no-loss .xlsx/.xlsm save.
Table: A worksheet table (authoring) — a styled, autofiltered range with named header columns (the OOXML <table> feature).
TextRun: One run of a rich (mixed-format) string: a text fragment plus the font applied to it. Author a multi-format cell with Sheet::write_rich; on read a rich string surfaces as its concatenated text.
Workbook: A workbook — parsed from .xls/.xlsx, or built for authoring via Workbook::new.
WorkbookMetadata: Public workbook-level metadata.
WorkbookReport: A compact, deterministic diagnose report for a workbook.

Enums§

BorderStyle: A single border edge style.
Cell: A typed cell value — the reader API. Mirrors the common spreadsheet cell kinds; dates are pre-rendered to an ISO string (no chrono dependency).
CellErrorType: Calamine-style typed spreadsheet error value.
CfRule: A conditional-formatting rule.
ChartKind: Chart kind.
DvKind: Data-validation kind.
DvOp: Data-validation comparison operator.
EditCapability: Edit/save capability for a Spreadsheet.
EditReadOnlyReason: Why a Spreadsheet cannot be edited/saved package-preservingly.
Error: Errors produced while opening or decoding a .xls workbook.
FormatPattern: Excel cell fill pattern.
FormatScript: Font superscript/subscript setting.
FormulaEvaluation: Result of evaluating a formula cell.
FormulaUnsupportedReason: Why a formula could not be evaluated deterministically.
HAlign: Horizontal cell alignment.
HeaderRow: Header-row selection policy for serde row deserialization.
ImageFmt: Image format for an embedded Image.
SheetType: Type of sheet in workbook metadata.
SheetVisible: Sheet visibility state.
SparklineKind: Sparkline kind for an in-cell mini chart.
VAlign: Vertical cell alignment.
WriteError: The error type returned by Workbook::to_xlsx_checked. A problem found by the checked validator before any .xlsx bytes are emitted.

Traits§

DataType: Calamine-style value inspection trait implemented by Cell/Data.
Reader: Calamine-style read facade for generic workbook consumers.

Functions§

deserialize_as_date_1900_or_none: Deserialize a spreadsheet cell as a 1900-epoch chrono date, returning None for invalid cells.
deserialize_as_date_1900_or_string: Deserialize a spreadsheet cell as a 1900-epoch chrono date, preserving invalid cells as text.
deserialize_as_date_1904_or_none: Deserialize a spreadsheet cell as a 1904-epoch chrono date, returning None for invalid cells.
deserialize_as_date_1904_or_string: Deserialize a spreadsheet cell as a 1904-epoch chrono date, preserving invalid cells as text.
deserialize_as_datetime_1900_or_none: Deserialize a spreadsheet cell as a 1900-epoch chrono datetime, returning None for invalid cells.
deserialize_as_datetime_1900_or_string: Deserialize a spreadsheet cell as a 1900-epoch chrono datetime, preserving invalid cells as text.
deserialize_as_datetime_1904_or_none: Deserialize a spreadsheet cell as a 1904-epoch chrono datetime, returning None for invalid cells.
deserialize_as_datetime_1904_or_string: Deserialize a spreadsheet cell as a 1904-epoch chrono datetime, preserving invalid cells as text.
deserialize_as_duration_or_none: Deserialize a spreadsheet cell as a chrono duration, returning None for invalid cells.
deserialize_as_duration_or_string: Deserialize a spreadsheet cell as a chrono duration, preserving invalid cells as text.
deserialize_as_f64_or_none: Deserialize a spreadsheet cell as f64, returning None for invalid cells.
deserialize_as_f64_or_string: Deserialize a spreadsheet cell as f64, preserving invalid cells as text.
deserialize_as_i64_or_none: Deserialize a spreadsheet cell as i64, returning None for invalid cells.
deserialize_as_i64_or_string: Deserialize a spreadsheet cell as i64, preserving invalid cells as text.
deserialize_as_time_1900_or_none: Deserialize a spreadsheet cell as a 1900-epoch chrono time, returning None for invalid cells.
deserialize_as_time_1900_or_string: Deserialize a spreadsheet cell as a 1900-epoch chrono time, preserving invalid cells as text.
deserialize_as_time_1904_or_none: Deserialize a spreadsheet cell as a 1904-epoch chrono time, returning None for invalid cells.
deserialize_as_time_1904_or_string: Deserialize a spreadsheet cell as a 1904-epoch chrono time, preserving invalid cells as text.
excel_serial_to_datetime: Convert an Excel date/time serial to calendar parts.
excel_serial_to_duration: Convert an Excel duration serial to chrono’s chrono::Duration.
excel_serial_to_naive_datetime: Convert an Excel date/time serial to chrono’s chrono::NaiveDateTime.
extract_text: Convenience: decode .xls bytes into normalized plain text. Errors with Error::NoText if nothing indexable was found.

Type Aliases§

Data: Calamine-style data value name for generic read-side code.
DataRef: Calamine-style borrowed data value name for generic read-side code.
DeError: Error type returned by range row deserialization.
FormatAlign: Writer alignment enum alias for format-builder APIs.
FormatBorder: Writer border enum alias for format-builder APIs.
Result: Convenience alias.

Crate rxls

Crate rxls Copy item path

Modules§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate rxls