Crate calamine

Rust Excel/OpenDocument reader

Status

calamine is a pure Rust library to read Excel and OpenDocument Spreadsheet files.

Read both cell values and vba project.

Examples

use calamine::{Reader, open_workbook, Xlsx, Data};

// opens a new workbook
let mut workbook: Xlsx<_> = open_workbook(path).expect("Cannot open file");

// Read whole worksheet data and provide some statistics
if let Ok(range) = workbook.worksheet_range("Sheet1") {
    let total_cells = range.get_size().0 * range.get_size().1;
    let non_empty_cells: usize = range.used_cells().count();
    println!("Found {} cells in 'Sheet1', including {} non empty cells",
             total_cells, non_empty_cells);
    // alternatively, we can manually filter rows
    assert_eq!(non_empty_cells, range.rows()
        .flat_map(|r| r.iter().filter(|&c| c != &Data::Empty)).count());
}

// Check if the workbook has a vba project
if let Some(Ok(mut vba)) = workbook.vba_project() {
    let vba = vba.to_mut();
    let module1 = vba.get_module("Module 1").unwrap();
    println!("Module 1 code:");
    println!("{}", module1);
    for r in vba.get_references() {
        if r.is_missing() {
            println!("Reference {} is broken or not accessible", r.name);
        }
    }
}

// You can also get defined names definition (string representation only)
for name in workbook.defined_names() {
    println!("name: {}, formula: {}", name.0, name.1);
}

// Now get all formula!
let sheets = workbook.sheet_names().to_owned();
for s in sheets {
    println!("found {} formula in '{}'",
             workbook
                .worksheet_formula(&s)
                .expect("error while getting formula")
                .rows().flat_map(|r| r.iter().filter(|f| !f.is_empty()))
                .count(),
             s);
}

Modules

• vba
  Parse vbaProject.bin file

Structs

• Cell
  A struct to hold cell position and value
• Cells
  A struct to iterate over all cells
• Dimensions
  Dimensions info
• ExcelDateTime
  Structure for Excel date and time representation.
• Metadata
  Common file metadata
• Ods
  An OpenDocument Spreadsheet document parser
• Range
  A struct which represents a squared selection of cells
• RangeDeserializer
  A configured Range deserializer.
• RangeDeserializerBuilder
  Builds a Range deserializer with some configuration options.
• Rows
  An iterator to read Range struct row by row
• Sheet
  Metadata of sheet
• Table
  Struct with the key elements of a table
• UsedCells
  A struct to iterate over used cells
• Xls
  A struct representing an old xls format file (CFB)
• XlsOptions
  Options to perform specialized parsing.
• Xlsb
  A Xlsb reader
• Xlsx
  A struct representing xml zipped excel file Xlsx, Xlsm, Xlam

Enums

• CellErrorType
  An enum to represent all different errors that can appear as a value in a worksheet cell
• Data
  An enum to represent all different data types that can appear as a value in a worksheet cell
• DataRef
  An enum to represent all different data types that can appear as a value in a worksheet cell
• DeError
  A cell deserialization specific error enum
• Error
  A struct to handle any error and a message
• ExcelDateTimeType
  Excel datetime type. Possible: date, time, datetime, duration. At this time we can only determine datetime (date and time are datetime too) and duration.
• OdsError
  An enum for ods specific errors
• SheetType
  Type of sheet
• SheetVisible
  Type of visible sheet
• Sheets
  A wrapper over all sheets when the file type is not known at static time
• XlsError
  An enum to handle Xls specific errors
• XlsbError
  A Xlsb specific error
• XlsxError
  An enum for Xlsx specific errors

Traits

• CellType
  A trait to constrain cells
• DataType
  A trait to represent all different data types that can appear as a value in a worksheet cell
• Reader
  A trait to share spreadsheets reader functions across different FileTypes
• ToCellDeserializer
  Constructs a deserializer for a CellType.

Functions

• deserialize_as_f64_or_none
  A helper function to deserialize cell values as f64, useful when cells may also contain invalid values (i.e. strings). It applies the [as_f64] method to the cell value, and returns Ok(Some(value_as_f64)) if successful or Ok(None) if unsuccessful, therefore never failing. This function is intended to be used with Serde’s deserialize_with field attribute.
• deserialize_as_f64_or_string
  A helper function to deserialize cell values as f64, useful when cells may also contain invalid values (i.e. strings). It applies the [as_f64] method to the cell value, and returns Ok(Ok(value_as_f64)) if successful or Ok(Err(value_to_string)) if unsuccessful, therefore never failing. This function is intended to be used with Serde’s deserialize_with field attribute.
• deserialize_as_i64_or_none
  A helper function to deserialize cell values as i64, useful when cells may also contain invalid values (i.e. strings). It applies the [as_i64] method to the cell value, and returns Ok(Some(value_as_i64)) if successful or Ok(None) if unsuccessful, therefore never failing. This function is intended to be used with Serde’s deserialize_with field attribute.
• deserialize_as_i64_or_string
  A helper function to deserialize cell values as i64, useful when cells may also contain invalid values (i.e. strings). It applies the [as_i64] method to the cell value, and returns Ok(Ok(value_as_i64)) if successful or Ok(Err(value_to_string)) if unsuccessful, therefore never failing. This function is intended to be used with Serde’s deserialize_with field attribute.
• open_workbook
  Convenient function to open a file with a BufReader
• open_workbook_auto
  Opens a workbook and define the file type at runtime.
• open_workbook_auto_from_rs
  Opens a workbook from the given bytes.
• open_workbook_from_rs
  Convenient function to open a file with a BufReader