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.
ChartCachedPoint: One indexed value retained from an OOXML chart cache.
ChartSeriesCache: Bounded cached inputs for one chart series.
ChartSeriesStyle: Bounded visual metadata retained for one imported chart series.
ChartTextStyle: Uniform effective text style retained for one semantic imported-chart role.
ChartTextStyles: Fixed-cardinality text-style sidecar for semantic imported-chart roles.
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.
CommentAuthor: Author input for Sheet::add_comment.
CondFormat: A conditional-formatting rule applied to a cell range (authoring).
ConditionalFormatMetadata: Read-side OOXML details retained beside a public CondFormat.
CsvOptions: Stable options for deterministic CSV export.
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.
DisplayCell: One deduplicated, display-ready worksheet cell.
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.
DrawingCrop: Source drawing crop, normalized to parts per million of each edge.
DrawingMetadata: Bounded rendering sidecar for a worksheet drawing object.
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.
FormulaRangeRowUsedCells: Iterator over non-empty formulas in one borrowed FormulaRangeRow.
FormulaRangeRows: Iterator over borrowed FormulaRangeRow views.
HeaderFooterMetadata: Distinct source header/footer strings and their authored behavior flags.
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.
LocalDefinedName: A worksheet-scoped defined name retained independently from global names.
PageSetup: Print / page setup for a worksheet (authoring). All fields optional; an unset field uses Excel’s default.
ParseProvenance: Deterministic provenance retained after a successful workbook parse.
Picture: Workbook-level embedded picture metadata for calamine-style read facades.
PrintLoss: One aggregated source print-metadata loss boundary.
PrintMetadata: Bounded, loss-aware source print metadata retained beside PageSetup.
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.
RangeRowUsedCells: Iterator over non-empty cells in one borrowed RangeRow.
RangeRows: Iterator over borrowed RangeRow views.
ReportEvaluation: Bounded formula evaluation distribution used by library and CLI reports.
ReportFeatures: Worksheet feature totals from metadata and surface APIs.
ReportProperties: Document properties surfaced in the diagnose report.
ReportStats: Stable workbook stats used by the diagnose report.
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.
StyleLoss: One aggregated source-style loss boundary.
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; readers retain supported run metadata through Sheet::rich_text_runs.
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.
ChartBarDirection: Orientation of an OOXML barChart retained beside ChartKind::Bar.
ChartFrameFill: Fill paint retained from an imported chart-space frame.
ChartFrameStyleLossKind: Typed reason that an imported chart-frame style needs a rendering fallback.
ChartKind: Chart kind.
ChartMarkerSymbol: Marker shape retained for one imported chart series.
ChartSeriesStyleLossKind: Typed reason that an imported chart-series style needs a rendering fallback.
ChartUnsupportedReason: Unsupported source-chart construct retained for explicit placeholder rendering.
ContainerParseMode: Container path used to produce a workbook.
CsvExportError: Failure returned by export_csv.
CsvFormulaPolicy: Policy for text fields that spreadsheet programs may interpret as formulas.
CsvNewline: Record separator used by export_csv.
DrawingAnchorBehavior: How a drawing responds when its anchor cells are moved or resized.
DrawingObjectKind: Kind of object described by DrawingMetadata.
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, decoding, exporting, or editing a spreadsheet.
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.
HeaderFooterKind: One of the six independently authored worksheet header/footer strings.
HeaderRow: Header-row selection policy for serde row deserialization.
ImageFmt: Image format for an embedded Image.
MarkupExportError: Failure returned by export_html or export_markdown.
MarkupFormat: Markup format selected by a checked HTML or Markdown export.
PrintFidelity: Fidelity of source print metadata retained by a worksheet reader.
PrintLossKind: Stable reason why source print metadata could not be represented exactly.
PrintPageOrder: Authored order used to traverse a worksheet’s printed pages.
RecoveryCode: Stable reason that a successful parse used a bounded recovery path.
SheetType: Type of sheet in workbook metadata.
SheetVisible: Sheet visibility state.
SparklineKind: Sparkline kind for an in-cell mini chart.
StyleFidelity: Fidelity of worksheet style information retained in the public model.
StyleLossKind: A bounded, typed reason why source styling could not be represented exactly.
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.

Constants§

DEFAULT_EXPORT_MAX_BYTES: Default maximum size of one in-memory export result (256 MiB).
MAX_PARSE_RECOVERY_CODES: Maximum number of recovery codes retained for one successful parse.
REPORT_SCHEMA_VERSION: Current public diagnose JSON contract version.

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.
export_csv: Export one worksheet as deterministic, bounded CSV.
export_html: Export one worksheet as a bounded HTML table fragment.
export_markdown: Export one worksheet as bounded GitHub-flavored Markdown.
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§

Constants§

Traits§

Functions§

Type Aliases§

Crate rxls