Crate crabxl

Expand description

Rust spreadsheet processing with bounded streaming XLSX reads.

Reads include sparse scalars, bounded plain/rich strings, numeric and ISO dates, shared style catalogs and normal formulas. Sequential creation shares the core models. Other spreadsheet features remain planned; unsupported selected cells fail loudly.

use crabxl::{AccessPattern, MemoryPolicy, ReadData, WorkbookReader};
let mut workbook = WorkbookReader::open("numbers.xlsx")?;
let output = workbook.read_with_policy(
    "Sheet", AccessPattern::RepeatedAccess, MemoryPolicy::default(),
)?;
println!("{:?}", output.decision);
match output.data {
    ReadData::Materialized(sheet) => println!("{} rows", sheet.rows.len()),
    ReadData::Streaming(mut rows) => while let Some(row) = rows.next_row()? {
        println!("{:?}", row.index);
    },
}

Structs§

ActiveViewSelection: Result of serializing a requested view index against sheet visibility.
AdaptiveRead: An automatically selected read strategy and its inspectable diagnostics.
Alignment: Cell alignment overrides with absent values retained.
ArgbLiteral: Compact validated ARGB spelling, without allocating an owned color string.
AutoMemory: Automatic budget controls. These tune an operation, not total process RSS.
Border: Complete border components, including internal and directional edges.
BorderSide: One optional border edge; absence and an empty edge remain distinct.
Cell: A present cell with its actual coordinate.
CellAddress: A validated cell position, independent of any workbook.
CellError: A literal spreadsheet error, separate from a library I/O/parser error. Unknown future error tokens remain readable without losing their spelling.
CellFormat: A format record referring to workbook component tables.
CellRange: A validated finite rectangle, including both end coordinates.
CellStyle: Complete appearance components for registering a new shared cell format. Imported component/base-format IDs and named-style metadata live in StyleCatalog.
CellText: Owned literal text. Indirection keeps common numeric cells compact.
Color: Color identity and optional tint without eager RGB conversion.
ColumnDimension: Sparse worksheet dimension metadata and shared appearance identities. Explicit properties for one inclusive worksheet column interval.
ColumnIndex: A validated zero-based worksheet column.
DataTableOptions: What-if input layout and optional source flags.
DifferentialStyle: Sparse appearance overrides; absent components do not install cell defaults.
EditLimits: Limits for one explicitly materialized editable sheet.
EditorOptions: Budgets for a lazy package editor and its owned value overlays.
Error: A spreadsheet error retaining the affected part, cell, and underlying cause. Details are allocated only on failure, keeping successful Result values small.
ExactInteger: An exact signed decimal integer exceeding the reader’s i64 fast path.
ExcelDateTime: Exact finite XLSX serial and its interpretation. No timezone is implied. Serial 60 in the Windows epoch is retained as Excel’s fictitious leap day; converting that value to another calendar epoch is rejected.
Formula: An expression with an optional typed cache and structured encoding metadata; no calculation engine or fabricated cache is implied.
FormulaAnnotations: Read-side cell/value metadata references attached to a formula. Literal source indices are retained independently of expression and cache. Their metadata part graphs are not interpreted or recreated by this model.
FormulaFlag: Optional boolean meaning plus original spelling for public properties which the pinned reference exposes as source strings.
FormulaFlags: Optional common calculation hints; no calculation engine is implied.
FormulaMetadata: Structured formula metadata; optional fields retain absence rather than installing flags/ranges or fabricated cached results.
FormulaReference: A literal formula reference or explicitly validated worksheet bounds. Literal spelling is retained without imposing geometry on public properties.
FormulaToken: A token borrowing its source spelling instead of allocating a string.
GradientFill: Full gradient fill rather than only upstream’s degree/stops subset.
GradientStop: Color at a gradient position.
Hyperlink: Resolved hyperlink properties; package relationship IDs are source hints. The owner coordinate belongs to the worksheet; an optional declaration reference preserves independently mutable public metadata.
HyperlinkOutput: A declaration and its planned worksheet-local output relationship identity. The projection borrows canonical payloads and never expands covered cells.
Hyperlinks: Sparse point links with logarithmic lookup and constant-time byte accounting. Range metadata remains compact; covered coordinates borrow the same payload.
LoadOptions: Managed policy for a source-backed canonical workbook bank.
LoadedWorkbook: Owns a seekable original package and the canonical workbook bank. Source styles transfer into the bank without cloning; only date classifications stay in the reader. Sheets decode lazily into independently bounded temporary models before a stable-ID commit. This is explicit editable-model loading, not a streaming row mode or a whole-process RSS cap.
MemoryAllowance: Runtime-independent diagnostics for a managed operation allowance. Existing catalogs, dependency allocations and caller data are additional; this is a snapshot of availability, not a reservation or hard RSS ceiling.
MergedCellRange: A finite merged rectangle and its shared edge/interior appearances. No covered cell objects are allocated. The owning coordinator prepares styles before registering geometry and retains the anchor’s physical value.
MergedRangeIter: Allocation-free traversal of indexed merged intervals.
MergedRanges: Bounded sparse merge declarations in registration order.
NamedStyle: Named-style metadata retaining its base-format identity.
NamedStyleOptions: Optional metadata for a newly registered named appearance.
NumberFormat: A declared number-format code without dense allocation from its numeric ID.
OwnedWorksheets: Consuming sheet iterator backed by the workbook’s original entry allocation.
PageBreak: An explicit page break, stored sparsely without expanding row/column ranges.
PageMargins: Six page margins in inches; finite negative descriptor values are retained.
PageSetup: Optional baseline paper/scaling/printer settings; integer source values use i64.
Pane: Split/frozen viewport. Literal cell spelling is not eagerly interpreted as geometry.
PaperDimension: A literal paper dimension validated against the baseline public prefix pattern. Trailing source spelling is retained, matching the reference descriptor.
PartInfo: Owned original-part inventory; content is not loaded into RAM.
PatternFill: Optional fill pattern and colors.
PhoneticProperties: Phonetic rendering settings; font identity belongs to the workbook font catalog.
PhoneticRun: Pronunciation text attached to a source character range.
PrintOptions: Optional print flags; explicit false remains distinct from absent.
PrintSettings: Canonical printing metadata. Absence of this entire model costs no sheet allocation.
Protection: Cell protection overrides, separate from sheet protection activation.
ReadDecision: Observable diagnostics for an automatic read operation.
ReadOptions: Projection performed before expensive cell-value decoding.
ResourceLimits: Limits for archive metadata, XML events, rows, and owned batches.
RichText: Owned rich text without a redundant flattened-string allocation.
RichTextRun: A contiguous run; None means ordinary text with no explicit run properties.
Row: An owned sparse row. Missing columns are not expanded into empty cells.
RowBatch: An owned, bounded collection of rows.
RowDimension: Sparse worksheet dimension metadata and shared appearance identities. Explicit properties for one worksheet row, independent of its cells.
RowIndex: A validated zero-based worksheet row.
Rows: A bounded, sparse worksheet row stream borrowing its workbook source.
RunFont: Optional run font overrides. Absent properties retain inheritance; explicit false properties must not be confused with absent ones.
SaveOptions: Controls CRC validation during copying. Rewritten XML is always parsed to EOF.
SaveStats: Per-save part counts and XML rewrite bytes. No worksheet temp files are used.
Selection: One focused cell/range selection; missing properties remain distinct from defaults.
SharedFormulaStats: Diagnostics for worksheet-local dependency work, separate from decoded cells.
SharedStringOptions: Shared-string component limits. Returned rows, archive metadata and dependencies are additional. These settings do not impose a hard process RSS limit.
SharedStringStats: Current shared-string component diagnostics, excluding returned owned values.
SheetData: An explicitly materialized scalar worksheet snapshot.
SheetDimensions: Sparse worksheet dimension metadata and shared appearance identities. Sparse canonical row/column metadata. Capacities participate in the owner cap.
SheetId: Opaque runtime sheet identity. It survives reorder/rename and cannot alias removed sheets or sheets in another workbook. It is not a persisted OOXML ID.
SheetInfo: One worksheet catalog entry, without loaded worksheet cells.
SheetView: Complete baseline worksheet view attributes, panes and selections.
SheetViews: Source-ordered worksheet views. No cells or dense ranges are retained here.
StyleCatalog: Shared imported style catalog. Original indices remain stable; declarations never reserve from an advertised count. Number-format classification is cached by canonical records; format codecs build bounded indexed cell lookups.
StyleId: A workbook-local index into the shared cell-format table.
StyleInteger: Exact style integer with an allocation-free signed i64 fast path. Large decimal identities are owned and never converted through floating point.
StyleLimits: Managed retained style storage and actual per-table record allowances.
StyleRegistry: One canonical catalog plus collision-checked indices. Styles share components, not whole appearance clones. Catalog access is borrowed and immutable so numeric IDs and deduplication indices cannot become stale.
StyleView: Borrowed appearance components for an existing cell-format identity. Source application/base-style flags remain accessible through format. This view installs no inferred defaults or locale-specific format codes.
TableStyle: Named custom table/pivot style with source-ordered elements.
TableStyleCatalog: Default style names and named custom definitions; advertised counts are ignored.
TableStyleElement: One table/pivot region’s differential formatting reference.
TemporalStyleIds: Canonical workbook-local temporal presets. IDs are resolved from each source catalog rather than assuming that imported records occupy 1..=4.
Theme: Exact theme-part bytes, including unknown drawing sections and typeface names. This core container does not interpret or validate an XML serialization.
ThemeCatalog: Typed read-side palette and font scheme. Original opaque theme bytes remain separately available; this is not a drawing/effect graph or editing model.
ThemeFontCollection: Major or minor theme font collection.
ThemeScriptFont: Supplemental typeface for a script, in document order.
ThemeTypeface: Typeface properties in a theme font collection. Empty typeface names are meaningful and remain distinct from absent elements.
Workbook: I/O-free owned workbook. Unknown original parts belong to the separate lazy XLSX editor; this model does not imply loaded-package structural preservation. Cells/styles/formulas use the same shared core representation.
WorkbookEditor: Owns the original source and a bounded overlay, keeping unknown XML/binary parts on their original source. save borrows self, so repeated saves retain images/macros and never consume the original or the pending edits.
WorkbookLimits: Aggregate allowances for an explicitly owned workbook and its sheet bank.
WorkbookParts: Ownership transfer for exporting a canonical workbook without catalog snapshots.
WorkbookReader: Owns a seekable ZIP source and a small sheet catalog, not worksheet cells.
WorkbookWriter: One-shot XLSX writer using bounded rows and owned temporary worksheets.
Worksheet: Sparse owned cell model. Structural edits move coordinates and preserve formulas verbatim; reference translation and feature graphs are separate. This is distinct from a lazy original-file editor and opaque preservation.
WorksheetEditor: Aggregate-budget mutation facade. Dropping restores the sheet’s configured personal ceiling; the workbook recomputes remaining aggregate space on each new borrow. Caller-owned removed values are outside the retained budget.
WorksheetRange: A worksheet-local range without allocating its covered cells. Absolute markers are accepted when parsing; geometry does not retain them. Sheet qualification belongs to the owning feature, rather than this type.
WriteOptions: Configurable resource limits for sequential worksheet spooling. These bound managed buffers/metadata and temporary XML, not process RSS.
WriteStats: Progress including logical temporary bytes, which also count unflushed XML.

Enums§

AccessPattern: Intended access pattern, used to choose a useful allocation strategy.
BorderLine: Cell border line style.
CalculationChainPolicy: Policy for the derived calculation order after values or formulas change.
CellMetadataReadPolicy: Treatment of opaque cell/value metadata references during value projection.
CellValue: Values supported by the current scalar reader.
ColorKind: Workbook-independent color reference. Theme/indexed colors retain identity.
DateEpoch: Workbook serial-date origin.
DateKind: Interpretation of a date/time serial value.
DateReadPolicy: How numeric date-formatted values outside the reference calendar range are read.
DecisionReason: The reason for the final automatic strategy.
ErrorKind: Stable categories suitable for matching in Rust or language adapters.
Fill: Shared fill model used by both imported catalogs and new styles.
FillPattern: Pattern fill style.
FontScheme: Theme font scheme.
FormulaReadPolicy: Validation of worksheet-local shared formula groups.
FormulaType: Formula encoding category; shared indices are local to one worksheet.
FormulaWritePolicy: Serialization of optional formula flags and empty data-table inputs.
GradientKind: Gradient geometry.
HorizontalAlignment: Horizontal cell alignment.
MemoryPolicy: Shared managed-memory policy for reading and editable operations.
MemorySource: Where effective available-memory information came from.
NonFiniteWritePolicy: XLSX serialization of nonfinite numeric values and formula caches.
PageOrder: page traversal order
PageOrientation: page orientation
PanePosition: A visible pane’s position relative to worksheet splits.
PaneState: Split or frozen viewport behavior.
PrintSettingsChange: An owned replacement of one printing component, leaving unrelated vectors in place. Incoming payloads are moved on success and dropped on failure; existing data is retained.
PrintedComments: printed comment placement
PrintedErrors: printed error representation
ReadData: Data returned by an automatic numeric read operation.
ReadMode: A selected numeric read strategy.
SharedFormulaIndex: Source shared-formula group identity. Missing and empty identifiers are distinct; noncanonical spelling is not normalized into another group.
SharedStringStorage: Placement of decoded shared strings and their index.
SheetKind: The kind of a workbook sheet.
SheetVisibility: Workbook catalog visibility of a worksheet or opaque sheet placeholder.
StyleComponent: One explicit appearance replacement, retaining all unrelated format fields. Large components are moved into the shared registry rather than cloned.
StyleWritePolicy: Serialization of alignment attributes with zero/false values.
TableStyleRegion: Table/pivot formatting region from the pinned public schema.
TextVerticalAlignment: Run baseline position.
ThemeColor: A DrawingML palette color, preserving system-color identity separately from its portable last-known RGB value. Color transforms require explicit support.
ThemeWritePolicy: Theme emission policy for newly created packages.
TokenKind: Lexical role of a formula token.
TokenSubtype: Additional operand or boundary meaning.
Underline: Underline shape, distinct from a missing run property.
VerticalAlignment: Vertical cell alignment.
ViewMode: Worksheet display mode, separate from printing configuration.

Constants§

BUILTIN_NUMBER_FORMATS: Known portable built-in format identities and reference-compatible spelling. Locale-specific reserved identities are deliberately not fabricated.
MAX_COLUMNS: Maximum worksheet columns in XLSX.
MAX_ROWS: Maximum worksheet rows in XLSX.

Functions§

builtin_number_format: Borrow a known built-in format without allocating a table or format string.
builtin_number_format_id: Find a portable built-in identity by its exact baseline spelling. Different locale spellings remain explicit custom format codes.
classify_formula_operand: Classify a public operand literal without evaluating or validating an expression.
classify_number_format: Classify an Excel format’s first section without allocation. Quoted/escaped literals and elapsed-time brackets retain the shared codec rules.
formula_position: Parse a formula tool’s one-based origin/destination. Unlike a physical cell, its row can extend beyond XLSX worksheet limits, matching baseline utilities. Column labels are limited to three letters; row labels must fit u64.
memory_allowance: Compute an allowance using the reader/editor’s shared availability policy. Reserves the configured parser components. Catalogs, dependencies, allocator overhead and caller-retained data are additional; this is not a hard RSS cap.
normalize_active_view: Normalize a deferred view without allocating a visible-sheet vector. Visible targets retain the original signed index. Otherwise select from the reference’s sliced visible-sheet list; no following candidate omits activeTab.
parse_iso8601: Parse pinned public ISO prefix behavior without reading reference source. Empty text is absent. Recognized calendar/clock prefixes ignore trailing text, including zone suffixes, as the compatibility baseline does. Only hour/minute/second elapsed durations are supported; no day/year notation.
read_rich_text: Decode one namespaced is or si element with explicit resource limits. Complete input consumption rejects extra roots and malformed trailing XML.
resolve_sheet_index: Resolve a signed, possibly relative display index without changing its spelling. Out-of-range indexes represent an unselected view.
tokenize_formula: Tokenize with a joint byte cap on source length and token/stack work capacity. Source input is borrowed. Unclosed function/group openers remain observable, matching the reference lexer; unmatched closers return a typed error.
translate_axis: Translate one validated positive row or three-letter column label. Absolute labels retain their spelling; relative labels use canonical output.
translate_expression: Shift relative A1 references in a bare or equals-prefixed expression. Absolute axes, sheet qualifiers, quoted strings and structured-reference brackets retain their context. Whole-row/column ranges do not expand cells. Output capacity is byte-bounded; input and caller data are additional. This is a translation scanner, not a complete formula tokenizer/parser. Dynamic spill syntax and unclosed quotes/brackets are rejected explicitly. Reference row labels beyond seven digits retain baseline named-range behavior.
visit_owned_hyperlink_ids: Visit ordinary owned-package identities in the exact shared writer order. The callback may retain selected identifiers; no persistent table is built.
write_rich_text: Write a namespaced inline rich value using the canonical format codec.

Type Aliases§

Font: Shared optional font properties, identical to rich-run overrides. Missing properties retain their identity rather than installing defaults.
FormulaRange: Existing name retained for callers constructing validated formula ranges.
Result: A result with a context-rich spreadsheet error.

Crate crabxl

Crate crabxl Copy item path

Structs§

Enums§

Constants§

Functions§

Type Aliases§

Crate crabxl