calamine

Excel Tables (named ranges with common formatting) are not loaded automatically to minimize overhead. You must explicitly call load_tables() before attempting to access them.

After loading, you can:

• List all table names in the workbook with table_names().
• List table names within a specific sheet with table_names_in_sheet(sheet_name).
• Retrieve an owned copy of a table's data using table_by_name(table_name).
• Retrieve a borrowed/referenced copy of a table's data (more efficient for large tables) using table_by_name_ref(table_name).

Both table_by_name and table_by_name_ref return a Table object containing the table's name, sheet name, columns, and a Range of data.

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

fn main() -> Result<(), Error> {
    let path = "tests/table-multiple.xlsx";

    // Open the workbook.
    let mut workbook: Xlsx<_> = open_workbook(path)?;

    // Load the tables in the workbook.
    workbook.load_tables()?;

    // Get the table by name. 
    // This returns an owned copy of the worksheet data.
    let table = workbook.table_by_name("Inventory")?;

    // Get the data range of the table. The data type is `&Range<Data>`.
    let data_range = table.data();

    // Access cell values using the Range API.
    assert_eq!(
        data_range.get((0, 1)),
        Some(&Data::String("Apple".to_string()))
    );

    Ok(())
}

To access Pivot Table data, you must first retrieve the workbook's pivot table metadata using pivot_tables(). This is a required step because Pivot Table data relies on metadata stored in PivotTableRef.

Once you have the PivotTables collection, you can iterate over the cached data for a specific table using pivot_table_data(), providing the worksheet name and the pivot table name.

use calamine::{open_workbook, Error, Xlsx};

fn main() -> Result<(), Error> {
    let path = "tests/pivots.xlsx";

    // Open the workbook.
    let mut workbook: Xlsx<_> = open_workbook(path)?;

    // Must retrieve necessary metadata before reading Pivot Table data.
    let pivot_tables = workbook.pivot_tables()?;

    // Get the Pivot Table data by referencing the pivot table name and the worksheet it resides.
    for row in workbook.pivot_table_data(&pivot_tables, "PivotSheet1", "PivotTable1")? {
             // Do something.
    }

    Ok(())
}

Use RangeDeserializerBuilder to configure how a spreadsheet Range is deserialized into Rust types using Serde. You can control whether the first row is treated as a header and specify which headers to include.

Header Options

• No headers: Use .has_headers(false) to treat every row as data (including the first row).
• All headers: Use .has_headers(true) (default) to treat the first row as a header row. This allows deserializing into structs or maps using header names.
• Custom headers: Use .with_headers(&["name1", "name2"]) to only include specific columns based on their header names.
• Automatic struct headers: Use .with_deserialize_headers::<T>() where T is your target struct. This automatically extracts the required header names from the struct's field names.

use calamine::{open_workbook, Error, Xlsx, Reader, RangeDeserializerBuilder};

fn main() -> Result<(), Error> {
    let path = "path/to/file.xlsx";
    let mut workbook: Xlsx<_> = open_workbook(path)?;
    let range = workbook.worksheet_range("Sheet1")?;

    // Example 1: No headers (treat first row as data)
    let mut iter = RangeDeserializerBuilder::new()
        .has_headers(false)
        .from_range(&range)?;

    // Example 2: Custom headers (only 'value' and 'label' columns)
    let mut iter = RangeDeserializerBuilder::with_headers(&["value", "label"])
        .from_range(&range)?;

    // Example 3: Automatic headers from a struct
    #[derive(serde::Deserialize)]
    struct Record {
        label: String,
        value: f64,
    }
    let mut iter = RangeDeserializerBuilder::with_deserialize_headers::<Record>()
        .from_range(&range)?;

    if let Some(result) = iter.next() {
        let record: Record = result.map_err(|e| ...)?;
        Ok(())
    }
    Ok(())
}