Calamine

https://github.com/tafia/calamine
Admin
Calamine is a pure Rust library for reading and deserializing Excel and OpenDocument spreadsheet...
Tokens:132,272
Snippets:739
Trust Score:7.5
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Range::from_sparse usage example

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/range.md

Demonstrates creating a `Range` from a sparse vector of `Cell`s using `Range::from_sparse`, and checking its start and height.

```rust
use calamine::{Cell, Data, Range};

let cells = vec![
    Cell::new((2, 2), Data::Int(1)),
    Cell::new((9, 2), Data::Int(1)),
];
let range = Range::from_sparse(cells);
assert_eq!(range.start(), Some((2, 2)));
assert_eq!(range.height(), 8); // rows 2..=9
```

--------------------------------

### Range value access and growth example

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/range.md

Demonstrates using set_value, get, and get_value on a Range. set_value within bounds does not resize; setting outside bounds grows the range. get uses relative positions, get_value uses absolute positions, and both return None for out-of-range positions.

```rust
use calamine::{Data, Range};

let mut range = Range::new((1, 1), (3, 3));
range.set_value((2, 2), Data::Int(123));           // within bounds, no resize
assert_eq!(range.get((1, 1)), Some(&Data::Int(123))); // relative lookup
assert_eq!(range.get_value((2, 2)), Some(&Data::Int(123))); // absolute lookup
assert_eq!(range.get_value((0, 0)), None);             // outside the range

// Growing via set_value:
range.set_value((5, 5), Data::Bool(true));             // range is resized
assert_eq!(range.end(), Some((5, 5)));
```

--------------------------------

### Cell usage example

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/range.md

Shows how to create a `Cell` with `Cell::new` and access its position and value using `get_position` and `get_value`.

```rust
use calamine::{Cell, Data};

let cell = Cell::new((2, 3), Data::Int(42));
assert_eq!(cell.get_position(), (2, 3));
assert_eq!(cell.get_value(), &Data::Int(42));
```

--------------------------------

### Usage example with deserialize_as_f64_or_none

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/lib.md

Demonstrates using `deserialize_as_f64_or_none` in a Serde struct to convert non-numeric cells to `None` instead of failing. Requires the `calamine` crate and the `serde` derive feature.

```rust
use calamine::{deserialize_as_f64_or_none, open_workbook, RangeDeserializerBuilder, Reader, Xlsx};
use serde::Deserialize;

#[derive(Deserialize)]
struct Record {
    metric: String,
    #[serde(deserialize_with = "deserialize_as_f64_or_none")]
    value: Option<f64>, // cells that are not numbers become None instead of failing
}

let mut workbook: Xlsx<_> = open_workbook("data.xlsx").unwrap();
let range = workbook.worksheet_range("Sheet1").unwrap();
let mut iter = RangeDeserializerBuilder::with_headers(&["metric", "value"]).from_range(&range).unwrap();
for result in iter {
    let record: Record = result.unwrap();
    println!("{} -> {:?}", record.metric, record.value);
}
```

--------------------------------

### open_workbook_from_rs usage with Cursor

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/lib.md

Example of using `open_workbook_from_rs` with a `Cursor<Vec<u8>>` to read an XLSX file from in-memory bytes.

```rust
use std::io::Cursor;
use calamine::{open_workbook_from_rs, Reader, Xlsx};

let bytes: Vec<u8> = std::fs::read("data.xlsx").unwrap();
let mut workbook: Xlsx<Cursor<Vec<u8>>> =
    open_workbook_from_rs(Cursor::new(bytes)).unwrap();
let name = workbook.sheet_names().remove(0);
let _range = workbook.worksheet_range(&name).unwrap();

```

--------------------------------

### Data usage example

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/datatype.md

Shows how to construct `Data` values using `From` impls and compare them with primitives. Demonstrates `Data::from("hello")`, `Data::Int(3)`, `Data::Bool(true)`, `Data::from(Option::<i64>::None)`, and `as_f64()`.

```rust
use calamine::Data;

let cell = Data::from("hello");          // Data::String
assert_eq!(cell, "hello");                // PartialEq<&str>
assert_eq!(Data::Int(3), 3i64);           // PartialEq<i64>
assert_eq!(Data::Bool(true), true);       // PartialEq<bool>
let opt: Option<i64> = None;
assert_eq!(Data::from(opt), Data::Empty); // From<Option<T>>
assert!(Data::Int(5).as_f64() == Some(5.0));
```

--------------------------------

### Range::new

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/range.md

Creates a new Range with the given start and end positions, populating the rectangle with default values.

```APIDOC
## Range::new

### Description
Creates a new `Range` with the given start and end positions, populating the rectangle with `T::default()`. Panics if `start > end`.

### Method
`pub fn new(start: (u32, u32), end: (u32, u32)) -> Range<T>`

### Parameters
- `start` ((u32, u32)) - Required - The zero-based (row, column) of the top-left corner.
- `end` ((u32, u32)) - Required - The zero-based (row, column) of the bottom-right corner.

### Returns
- `Range<T>` - The new range.

### Panics
Panics if `start > end`.

### Example
```rust
use calamine::Range;

let range = Range::new((0, 0), (2, 2));
```
```

--------------------------------

### Example: iterate VBA modules and print decoded content

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/vba.md

Opens an XLSX workbook with macros, retrieves the VBA project, and prints each module's name and decoded content. Uses the if-let pattern to handle the optional VbaProject.

```rust
use calamine::{open_workbook, Error, Reader, Xlsx};

fn main() -> Result<(), Error> {
    let mut workbook: Xlsx<_> = open_workbook("macros.xlsm")?;
    if let Ok(Some(vba)) = workbook.vba_project() {
        for module_name in vba.get_module_names() {
            println!("===== {module_name} =====");
            println!("{}", vba.get_module(module_name)?);
        }
    }
    Ok(())
}
```

--------------------------------

### Read xlsx rows with excelize (OpenFile, Rows)

Source: https://github.com/tafia/calamine/blob/master/README.md

Excelize benchmark example: opens an xlsx file, selects a worksheet by name, and iterates over its rows. Includes error handling and deferred file close.

```go
package main

import (
        "fmt"
        "github.com/xuri/excelize/v2"
)

func main() {
        // Open workbook
        file, err := excelize.OpenFile(`NYC_311_SR_2010-2020-sample-1M.xlsx`)

        if err != nil {
                fmt.Println(err)
                return
        }

        defer func() {
                // Close the spreadsheet.
                if err := file.Close(); err != nil {
                        fmt.Println(err)
                }
        }()

        // Select worksheet
        rows, err := file.Rows("NYC_311_SR_2010-2020-sample-1M")
        if err != nil {
                fmt.Println(err)
                return
        }

        // Iterate over rows
        for rows.Next() {
        }
}
```

--------------------------------

### Range<T> constructors

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/range.md

Shows the constructors for `Range<T>`: `new`, `empty`, and `from_sparse`. `new` panics if `start > end`; `from_sparse` computes bounds from cells and is preferred for efficiency.

```rust
impl<T: CellType> Range<T> {
    #[inline]
    pub fn new(start: (u32, u32), end: (u32, u32)) -> Range<T>
    // panics: assert!(start <= end, "invalid range bounds")

    #[inline]
    pub fn empty() -> Range<T>

    pub fn from_sparse(cells: Vec<Cell<T>>) -> Range<T>
}
```

--------------------------------

### Iterating rows from open_workbook_auto

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/auto.md

Example that opens an .xlsm file with open_workbook_auto and prints all rows from each sheet. Demonstrates error handling with the ? operator.

```rust
use calamine::{open_workbook_auto, Error, Reader};

fn main() -> Result<(), Error> {
    let mut workbook = open_workbook_auto("input.xlsm")?; // Sheets<BufReader<File>>
    let names = workbook.sheet_names();
    for name in names {
        for row in workbook.worksheet_range(&name)?.rows() {
            println!("{row:?}");
        }
    }
    Ok(())
}
```

--------------------------------

### open_workbook usage with Xlsx

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/lib.md

Example of using `open_workbook` to open an XLSX file and read a worksheet range. The reader type is `Xlsx<_>`.

```rust
use calamine::{open_workbook, Reader, Xlsx};

let mut workbook: Xlsx<_> = open_workbook("data.xlsx").expect("cannot open workbook");
let range = workbook.worksheet_range("Sheet1").expect("cannot read sheet");
println!("{} cells", range.get_size().0 * range.get_size().1);

```

--------------------------------

### Reading ODS from bytes with open_workbook_auto_from_rs

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/auto.md

Example that reads a file into bytes and uses open_workbook_auto_from_rs with a Cursor to open an ODS workbook. Prints each sheet name and used cell count.

```rust
use std::io::Cursor;
use calamine::{open_workbook_auto_from_rs, Reader};

let bytes: Vec<u8> = std::fs::read("data.ods").unwrap();
let mut workbook = open_workbook_auto_from_rs(Cursor::new(bytes)).unwrap();
for (name, range) in workbook.worksheets() {
    println!("{name}: {}", range.used_cells().count());
}
```

--------------------------------

### Range iteration example: cells, used_cells, rows

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/range.md

Demonstrates iterating over a Range with cells(), used_cells(), and rows(). cells() includes empty cells, used_cells() skips default values, and rows() yields row slices. The output shows the iteration order.

```rust
use calamine::{Data, Range};

let mut range = Range::new((0, 0), (1, 1));
range[(0, 0)] = Data::Int(1);
range[(1, 1)] = Data::Int(2);

for (row, col, value) in range.cells() {
    print!("({row},{col})={value} ");
}
// (0,0)=1 (0,1)= (1,0)= (1,1)=2
println!();
assert_eq!(range.used_cells().count(), 2); // skips Data::Empty
assert_eq!(range.rows().count(), 2);
```

--------------------------------

### Using expand_shared_formula

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/xlsx-reader.md

Example of expanding a shared formula with relative references. The formula "A1+B1" shifted by (2,1) becomes "B3+C3".

```rust
use calamine::expand_shared_formula;

let expanded = expand_shared_formula("A1+B1", (0, 0), (2, 1)).unwrap();
assert_eq!(expanded, "B3+C3"); // relative refs shifted by (2, 1); $-refs stay put
```

--------------------------------

### Using expand_shared_formula_into

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/xlsx-reader.md

Example of expanding a shared formula into a buffer. Handles the RowNumberOverflow error case.

```rust
use calamine::expand_shared_formula_into;

let mut out = String::new();
let result = expand_shared_formula_into("$A$1+A2", (0, 0), (5, 0), &mut out);
match result {
    Ok(()) => println!("{}", out),        // "$A$1+A7"
    Err(calamine::XlsxError::RowNumberOverflow) =>
        println!("target outside the workbook grid"),
    Err(e) => println!("other formula error: {e}"),
}
```

--------------------------------

### Convert Table to Range via From/Into

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/range.md

Converts a Table<Data> into a Range<Data> using the From implementation. The example asserts that the cell at (0,1) contains the string "Apple".

```rust
use calamine::{open_workbook, Data, Error, Range, Xlsx};

fn main() -> Result<(), Error> {
    let mut workbook: Xlsx<_> = open_workbook("inventory-table.xlsx")?;
    workbook.load_tables()?;
    let table = workbook.table_by_name("Table1")?;
    // Convert a table into a plain data Range via From/Into.
    let data_range: Range<Data> = table.into();
    assert_eq!(data_range.get((0, 1)), Some(&Data::String("Apple".to_string())));
    Ok(())
}
```

--------------------------------

### Using open_workbook_auto with Sheets

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/auto.md

Shows how to open a workbook with unknown file type using open_workbook_auto, which returns a Sheets enum. The example reads a range from 'Sheet1' and prints the count of used cells.

```rust
use calamine::{open_workbook_auto, Reader, Sheets};

// File type is only known at runtime; `Sheets` wraps whichever succeeds.
let mut workbook: Sheets<_> = open_workbook_auto("whatever.xlsb").unwrap();

if let Ok(range) = workbook.worksheet_range("Sheet1") {
    println!("used cells: {}", range.used_cells().count());
}
```

--------------------------------

### open_workbook usage with Xls and error propagation

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/lib.md

Example of using `open_workbook` to open an XLS file, iterating over worksheets. The `R::Error` propagates through the root `Error` enum via `From`.

```rust
use calamine::{open_workbook, Error, Reader, Xls};

fn main() -> Result<(), Error> {
    // The R::Error propagates through the root `Error` enum via From.
    let mut workbook: Xls<_> = open_workbook("old.xls")?;
    for (name, range) in workbook.worksheets() {
        println!("{name}: {} used cells", range.used_cells().count());
    }
    Ok(())
}

```

--------------------------------

### Catching errors in consumer code

Source: https://github.com/tafia/calamine/blob/master/_autodocs/errors.md

Example Rust code demonstrating how to handle errors from `open_workbook_auto` and `worksheet_range` using the `Error` enum and pattern matching.

```APIDOC
## Catching errors in consumer code

### Description
Example of handling errors when opening a workbook and accessing a worksheet range.

### Code Example
```rust
use calamine::{open_workbook_auto, Error, Reader};

fn main() -> Result<(), Error> {
    match open_workbook_auto("file.xlsx") {
        Ok(mut wb) => {
            // Per-sheet errors are still possible:
            match wb.worksheet_range("Missing") {
                Err(Error::Xlsx(calamine::XlsxError::WorksheetNotFound(n))) =>
                    println!("no sheet {n}"),
                Err(e) => println!("{e}"),
                Ok(range) => println!("{}x{}", range.height(), range.width()),
            }
            Ok(())
        }
        Err(Error::Msg(m)) => Err(Error::Io(std::io::Error::new(
            std::io::ErrorKind::InvalidData, m,
        ))), // e.g. "Cannot detect file format"
        Err(e) => {
            // any wrapped format error:
            println!("open failed: {e}, source: {:?}", e.source());
            Ok(())
        }
    }
}
```

### Notes
- All error types implement `From` into `Error`, so `?` in a `Result<_, Error>` function works for any reader/deserializer error.
```

--------------------------------

### Get headers as strings from a range

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/range.md

Builds a range with a string and an integer cell, then calls `headers()`. The integer is rendered as a string (e.g., `7` becomes `"7"`). Asserts the returned vector matches the expected strings.

```rust
use calamine::{Data, Range};

let mut range = Range::new((0, 0), (0, 1));
range[(0, 0)] = Data::String("name".into());
range[(0, 1)] = Data::Int(7); // rendered as "7"
assert_eq!(range.headers(), Some(vec!["name".to_string(), "7".to_string()]));
```

--------------------------------

### Read xlsx rows with calamine (open_workbook, worksheet_range)

Source: https://github.com/tafia/calamine/blob/master/README.md

Calamine benchmark example: opens an xlsx workbook, retrieves a worksheet by name, and iterates over its rows. Uses open_workbook, Reader, and Xlsx types.

```rust
use calamine::{open_workbook, Reader, Xlsx};

fn main() {
    // Open workbook
    let mut excel: Xlsx<_> =
        open_workbook("NYC_311_SR_2010-2020-sample-1M.xlsx").expect("failed to find file");

    // Get worksheet
    let sheet = excel
        .worksheet_range("NYC_311_SR_2010-2020-sample-1M")
        .unwrap()
        .unwrap();

    // iterate over rows
    for _row in sheet.rows() {}
}
```

--------------------------------

### Using worksheet_range_ref with Xlsx

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/lib.md

Shows how to open a workbook and use worksheet_range_ref to iterate over cells with borrowed shared strings. The example prints the row, column, and string value for each cell that contains a shared string.

```rust
use calamine::{open_workbook, Reader, ReaderRef, Xlsx, DataRef};

let mut workbook: Xlsx<_> = open_workbook("big.xlsx").unwrap();
let range = workbook.worksheet_range_ref("Sheet1").unwrap();
// Strings come back as DataRef::SharedString(&str), borrowing the shared
// string table inside the workbook rather than copying.
for (row, col, value) in range.used_cells() {
    if let DataRef::SharedString(s) = value {
        println!("({row},{col}): {s}");
    }
}
```

--------------------------------

### Reading cells with DataRef and converting to owned Data

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/datatype.md

Shows how to open an XLSX workbook, get a worksheet range as DataRef, and match on cell values. Also demonstrates converting a borrowed SharedString into an owned Data using From<DataRef<'a>> for Data.

```rust
use calamine::{open_workbook, Reader, ReaderRef, Xlsx, DataRef};

let mut workbook: Xlsx<_> = open_workbook("data.xlsx").unwrap();
let range = workbook.worksheet_range_ref("Sheet1").unwrap();
for (_, _, value) in range.used_cells() {
    match value {
        DataRef::SharedString(s) => println!("shared: {s}"),
        DataRef::Int(v) => println!("int: {v}"),
        _ => {}
    }
}

// Borrowed -> owned:
let owned: calamine::Data = DataRef::SharedString("x").into();
```

--------------------------------

### Read xlsx rows with ClosedXML (XLWorkbook, Worksheet)

Source: https://github.com/tafia/calamine/blob/master/README.md

ClosedXML benchmark example: opens an xlsx workbook, gets the first worksheet, and iterates over its rows. Uses a using declaration for automatic disposal.

```csharp
using ClosedXML.Excel;

internal class Program
{
        private static void Main(string[] args)
        {
                // Open workbook
                using var workbook = new XLWorkbook("NYC_311_SR_2010-2020-sample-1M.xlsx");

                // Get Worksheet
                // "NYC_311_SR_2010-2020-sample-1M"
                var worksheet = workbook.Worksheet(1);

                // Iterate over rows
                foreach (var row in worksheet.Rows())
                {

                }
        }
}
```

--------------------------------

### Range error handling: out-of-bounds and panic

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/range.md

Shows that get returns None for positions outside the rectangle, while set_value panics if the position is above/left of start. The panic message is "absolute_position out of bounds".

```rust
// Error handling: positions outside the rectangle return None; positions
// above/left of start panic instead.
use calamine::{Data, Range};

let range = Range::<Data>::new((2, 2), (5, 5));
assert_eq!(range.get((0, 0)), None);   // relative: outside rectangle
// range.set_value((0, 0), Data::Empty); // PANICS: "absolute_position out of bounds"
```

--------------------------------

### RowDeserializer usage example with Data cells

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/de.md

Example of using RowDeserializer to deserialize a row of Data cells into a tuple (i64, f64). It demonstrates that RowDeserializer implements serde::Deserializer and can drive any Deserialize-owned target directly.

```rust
use calamine::{Data, RowDeserializer, ToCellDeserializer};
use serde::Deserialize;

let cells = [Data::Int(1), Data::Float(2.0)];
let indexes = [0usize, 1];
let row = RowDeserializer::new(&indexes, None, &cells, (0, 0));
// RowDeserializer implements serde::Deserializer, so it can drive any
// Deserialize-owned target directly:
let (a, b): (i64, f64) = Deserialize::deserialize(row).unwrap();
assert_eq!((a, b), (1, 2));
```

--------------------------------

### RangeDeserializer usage example with Xlsx workbook

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/de.md

Example of using RangeDeserializer via Range::deserialize to iterate over rows of a worksheet, deserializing each row into a tuple (String, f64). The iterator returns Result<(String, f64), DeError> and each next() consumes one row.

```rust
use calamine::{open_workbook, Error, Reader, Xlsx};

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

    let mut iter = range.deserialize::<(String, f64)>()?; // iterator of Result<(String, f64), DeError>
    let mut count = 0;
    while let Some(result) = iter.next() {
        let (label, _) = result?;
        println!("row {count}: {label}");
        count += 1;
    }
    Ok(())
}
```

--------------------------------

### Cell::get_value

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/range.md

Gets a borrow of the stored value of the cell.

```APIDOC
## Cell::get_value

### Description
Gets a borrow of the stored value of the cell.

### Method
`pub fn get_value(&self) -> &T`

### Parameters
None.

### Returns
- `&T` - A borrow of the stored value.

### Example
```rust
use calamine::{Cell, Data};

let cell = Cell::new((2, 3), Data::Int(42));
assert_eq!(cell.get_value(), &Data::Int(42));
```
```

--------------------------------

### Rust: Using epoch, tables, merged cells, and hyperlinks

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/xlsx.md

Opens an Xlsx workbook, checks the date system (1904 vs 1900), loads tables and prints their names, retrieves merged cells for 'Sheet1', and prints hyperlinks from the 'Links' sheet. Requires the calamine crate and a file named 'book.xlsx'.

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

fn main() -> Result<(), Error> {
    let mut workbook: Xlsx<_> = open_workbook("book.xlsx")?;
    let epoch = if workbook.has_1904_epoch() { "1904" } else { "1900" };
    println!("date system: {epoch}");

    workbook.load_tables()?;
    for name in workbook.table_names() {
        println!("table: {name}");
    }

    let merged = workbook.merge_cells_by_sheet_name("Sheet1")?;
    println!("merged regions: {merged:?}");

    let links = workbook.hyperlinks_by_sheet_name("Links")?;
    for link in &links {
        println!("{:?} -> {:?}", link.range, link.target);
    }
    Ok(())
}
```

--------------------------------

### Example: handle VBA module decoding failures with fallback to raw

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/vba.md

Opens an XLSX workbook with macros, retrieves the VBA project, and iterates over modules. Decoding to UTF-8 may fail on unusual MBCS bytes; falls back to raw bytes and prints the error and byte count. Uses the let-else pattern and matches on VbaError::ModuleNotFound.

```rust
use calamine::{open_workbook, Error, Reader, Xlsx};

fn main() -> Result<(), Error> {
    let mut workbook: Xlsx<_> = open_workbook("macros.xlsm")?;
    let Some(vba) = workbook.vba_project()? else {
        println!("no VBA project");
        return Ok(());
    };

    // Decoding to UTF-8 may fail on unusual MBCS bytes; fall back to raw.
    for name in vba.get_module_names() {
        match vba.get_module(name) {
            Ok(text) => println!("{name}: {text}"),
            Err(calamine::vba::VbaError::ModuleNotFound(_)) => println!("{name}: gone"),
            Err(e) => {
                let raw = vba.get_module_raw(name)?;
                println!("{name}: decode failed ({e}), raw {} bytes", raw.len());
            }
        }
    }
    Ok(())
}
```

--------------------------------

### Xls::merge_cells_by_sheet_id

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/xls.md

Gets merged cell dimensions by sheet index.

```APIDOC
## `Xls::merge_cells_by_sheet_id`

### Description
Gets the merged cells/regions in a worksheet by sheet index.

### Method
Instance method

### Signature
```rust
pub fn merge_cells_by_sheet_id(&self, id: usize) -> Result<Vec<Dimensions>, XlsError>
```

### Parameters
- `id` (`usize`) - Required - The sheet index.

### Returns
- `Result<Vec<Dimensions>, XlsError>` - The merged cell dimensions.

### Errors
- `XlsError::WorksheetNotFound("Sheet index {id} out of range")` - The sheet index is out of range.
```

--------------------------------

### Xls::merge_cells_by_sheet_name

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/xls.md

Gets merged cell dimensions by sheet name.

```APIDOC
## `Xls::merge_cells_by_sheet_name`

### Description
Gets the merged cells/regions in a worksheet by sheet name.

### Method
Instance method

### Signature
```rust
pub fn merge_cells_by_sheet_name(&self, name: &str) -> Result<Vec<Dimensions>, XlsError>
```

### Parameters
- `name` (`&str`) - Required - The sheet name.

### Returns
- `Result<Vec<Dimensions>, XlsError>` - The merged cell dimensions.

### Errors
- `XlsError::WorksheetNotFound(name)` - The specified worksheet was not found.
```

--------------------------------

### Cell::get_position

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/range.md

Gets the absolute (row, column) position of the cell.

```APIDOC
## Cell::get_position

### Description
Gets the absolute (row, column) position of the cell.

### Method
`pub fn get_position(&self) -> (u32, u32)`

### Parameters
None.

### Returns
- `(u32, u32)` - The absolute (row, column) position.

### Example
```rust
use calamine::{Cell, Data};

let cell = Cell::new((2, 3), Data::Int(42));
assert_eq!(cell.get_position(), (2, 3));
```
```

--------------------------------

### Dimensions struct definition

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/lib.md

Defines the Dimensions struct with start and end cell coordinates. Provides methods new, contains, and len. len() computes (end.0 - start.0 + 1) * (end.1 - start.1 + 1) and assumes end >= start; for the default (0,0)-(0,0) it returns 1. There is no is_empty helper.

```rust
/// Dimensions info
#[derive(Debug, Default, PartialEq, Eq, Hash, Ord, PartialOrd, Copy, Clone)]
pub struct Dimensions {
    /// start: (row, col)
    pub start: (u32, u32),
    /// end: (row, col)
    pub end: (u32, u32),
}
```

--------------------------------

### Using DataType methods on Data

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/datatype.md

Shows how to use `DataType` methods on a `Data::Int` value. `as_i64` returns the integer, `as_f64` converts to float, and `to_string` returns the string representation.

```rust
use calamine::{Data, DataType};

// DataType methods are available on both Data and DataRef.
let d = Data::Int(42);
assert_eq!(d.as_i64(), Some(42));
assert_eq!(d.as_f64(), Some(42.0));
assert_eq!(d.to_string(), "42");
```

--------------------------------

### Xlsb::worksheet_cells_reader

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/xlsb.md

Gets a cells reader for a given worksheet, allowing iteration over cells.

```APIDOC
## Xlsb::worksheet_cells_reader

### Description
Gets a cells reader for a given worksheet, allowing iteration over cells.

### Method
worksheet_cells_reader

### Parameters
- **name** (string) - Required - The name of the worksheet.

### Returns
- **Result<XlsbCellsReader<'a, RS>, XlsbError>** - A cells reader for the specified worksheet.

### Errors
- **XlsbError::WorksheetNotFound(name)** - If the worksheet is not found.
- Propagates RecordIter zip errors.
```

--------------------------------

### Xls::new_with_options

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/xls.md

Constructor for the `Xls` struct that parses an old xls format file (CFB) eagerly.

```APIDOC
## `Xls::new_with_options`

### Description
Creates a new `Xls` instance from a CFB (compound file binary) reader, using the provided `XlsOptions` to inform parsing. The whole workbook is parsed eagerly at construction.

### Method
Constructor

### Signature
```rust
pub fn new_with_options(mut reader: RS, options: XlsOptions) -> Result<Self, XlsError>
```

### Parameters
- `reader` (`RS: Read + Seek`) - Required - The CFB (compound file binary) source.
- `options` (`XlsOptions`) - Required - Codepage override and header-row options.

### Errors
- `XlsError::Io` / `Cfb` - Parsing the OLE container.
- `XlsError::EoStream` - End of stream.
- `XlsError::InvalidFormula` - Invalid formula.
- `XlsError::IfTab` - Invalid tab.
- `XlsError::Etpg` - Invalid ETPG.
- `XlsError::InvalidFormat { ifmt }` - Invalid format.
- `XlsError::Password` - Password-protected `EncryptedPackage`/`EncryptedSummary` streams.
- `CfbError::StreamNotFound("Workbook")` - No workbook stream exists.
```

--------------------------------

### Xls::worksheet_merge_cells_at

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/xls.md

Deprecated method to get merge cell dimensions by sheet index.

```APIDOC
## `Xls::worksheet_merge_cells_at`

### Description
Gets the worksheet merge cell dimensions by sheet index. Deprecated since 0.36.0; use `merge_cells_by_sheet_id()` instead.

### Method
Instance method

### Signature
```rust
pub fn worksheet_merge_cells_at(&self, n: usize) -> Option<Vec<Dimensions>>
```

### Parameters
- `n` (`usize`) - Required - The sheet index.

### Returns
- `Option<Vec<Dimensions>>` - `None` out of range.
```

--------------------------------

### Xls::worksheet_merge_cells

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/xls.md

Deprecated method to get merge cell dimensions by sheet name.

```APIDOC
## `Xls::worksheet_merge_cells`

### Description
Gets the worksheet merge cell dimensions by sheet name. Deprecated since 0.36.0; use `merge_cells_by_sheet_name()` instead.

### Method
Instance method

### Signature
```rust
pub fn worksheet_merge_cells(&self, name: &str) -> Option<Vec<Dimensions>>
```

### Parameters
- `name` (`&str`) - Required - The sheet name.

### Returns
- `Option<Vec<Dimensions>>` - `None` for unknown sheets.
```

--------------------------------

### VbaProject::new constructor

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/vba.md

Creates a new VbaProject from a CFB byte stream (e.g., the vbaProject.bin zip entry) and its length. Parses the CFB container, the dir stream, all REFERENCE records, and all module streams (decompressed). In normal usage, obtain a VbaProject via Reader::vba_project instead.

```rust
impl VbaProject {
    /// Create a new `VbaProject` out of the vbaProject.bin `ZipFile` or xls file
    ///
    /// Starts reading project metadata (header, directories, sectors and minisectors).
    pub fn new<R: Read>(r: &mut R, len: usize) -> Result<VbaProject, VbaError>
}
```

--------------------------------

### HeaderRow

Source: https://github.com/tafia/calamine/blob/master/_autodocs/configuration.md

Documentation for the HeaderRow enum used to configure the starting row when reading worksheets.

```APIDOC
## HeaderRow

### Description
Cross-format option to start reading at a given row, passed by value.

### Variants
- **FirstNonEmptyRow** (default) - No trimming; the first row is row 0 (XLSX/XLSB: the first row containing non-empty cells is kept).
- **Row(u32)** - 0-based first row to keep; everything above is dropped.

### Usage Example
```rust
use calamine::{HeaderRow, open_workbook, Reader, Xlsx};

let mut workbook: Xlsx<_> = open_workbook("data.xlsx").unwrap();
// Drop rows 0..3; the header (first kept) row is 3.
let sheet = workbook.with_header_row(HeaderRow::Row(3)).worksheet_range("Sheet1").unwrap();
```

### Behavior by Format
- **XLSX / XLSB**: lazy (streaming) - `with_header_row` takes effect during the worksheet read itself, saving work on large files. With `Row(idx)`, an empty header cell is injected at `(idx, first_non_empty_col)` when the first non-empty cell is below `idx`.
- **XLS / ODS**: the whole workbook is parsed eagerly at open; the header row clips the already-parsed `Range` on `worksheet_range` calls. No performance benefit.
```

--------------------------------

### XlsOptions

Source: https://github.com/tafia/calamine/blob/master/_autodocs/configuration.md

Documentation for the XlsOptions struct, the only public options struct in the calamine library.

```APIDOC
## XlsOptions

### Description
Options for reading legacy XLS files. Configure via `Xls::new_with_options(reader, options)`; `Reader::new` uses `XlsOptions::default()`.

### Fields
- **force_codepage** (`Option<u16>`) - Optional - Windows code-page identifier used to decode strings. Overrides the workbook's codepage record (which itself defaults to 1200/UTF-16 when absent). Unsupported codepages error with `XlsError::Cfb(CfbError::CodePageNotFound(u16))`.
- **header_row** (`HeaderRow`) - Optional - Header (first kept) row; defaults to `FirstNonEmptyRow`.

### Construction
Because the struct is `#[non_exhaustive]`, construct with `XlsOptions::default()` and set fields — you cannot use struct-literal syntax.

### Example
```rust
let mut options = XlsOptions::default();
options.force_codepage = Some(1252);
options.header_row = HeaderRow::FirstNonEmptyRow;
let reader = Xls::new_with_options(reader, options);
```
```

--------------------------------

### Range::empty

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/range.md

Creates an empty Range with start and end both at (0,0) and an empty inner vector.

```APIDOC
## Range::empty

### Description
Creates an empty `Range` with start and end both at (0,0) and an empty inner vector. Always `is_empty()`.

### Method
`pub fn empty() -> Range<T>`

### Parameters
None.

### Returns
- `Range<T>` - An empty range.

### Example
```rust
use calamine::Range;

let range = Range::empty();
```
```

--------------------------------

### Xls Reader Implementation Notes

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/xls.md

Implementation notes for the Xls reader in the calamine library, covering methods for reading worksheets, VBA projects, pictures, and constructing workbooks with options.

```APIDOC
## worksheet_range(name)

### Description
Clones the parsed range; with `HeaderRow::Row(idx)` clips the range to `(idx, start.1)..end`.

### Method
N/A (Rust method)

### Parameters
- **name** (string) - Required - Sheet name.

### Returns
Cloned range.

```

```APIDOC
## worksheet_formula(name)

### Description
Cloned `Range<String>`.

### Method
N/A (Rust method)

### Parameters
- **name** (string) - Required - Sheet name.

### Returns
Cloned `Range<String>`.

```

```APIDOC
## worksheets()

### Description
All sheets, cloned.

### Method
N/A (Rust method)

### Returns
All sheets, cloned.

```

```APIDOC
## vba_project()

### Description
Reads the `_VBA_PROJECT_CUR` directory (`Ok(None)` when absent) and parses the VBA project from the CFB.

### Method
N/A (Rust method)

### Returns
VBA project or `Ok(None)` when absent.

```

```APIDOC
## pictures() (feature `picture`)

### Description
Embedded OfficeArt picture data.

### Method
N/A (Rust method)

### Returns
Embedded OfficeArt picture data.

```

```APIDOC
## Xls::new_with_options(reader, options)

### Description
Creates a new Xls workbook with custom options, such as forcing a codepage or setting a header row.

### Method
N/A (Rust constructor)

### Parameters
- **reader** (BufReader<File>) - Required - The input reader.
- **options** (XlsOptions) - Required - Options for reading the workbook.

### Returns
`Result<Xls, XlsError>`.

### Errors
- `XlsError::Cfb(_)` - Corrupt OLE container.
- `XlsError::Password` - Workbook is encrypted.

```

--------------------------------

### Trait DataType

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/datatype.md

Documentation for the DataType trait in the calamine crate, including all its methods, conversion semantics, and usage examples.

```APIDOC
## Trait `DataType`

### Description
A trait to represent all different data types that can appear as a value in a worksheet cell. It provides methods to assess the type of the value and to retrieve or convert the value into various Rust types.

### Methods

#### `is_empty`
- **Signature**: `fn is_empty(&self) -> bool`
- **Description**: Assess if datatype is empty.

#### `is_int`
- **Signature**: `fn is_int(&self) -> bool`
- **Description**: Assess if datatype is an int.

#### `is_float`
- **Signature**: `fn is_float(&self) -> bool`
- **Description**: Assess if datatype is a float.

#### `is_bool`
- **Signature**: `fn is_bool(&self) -> bool`
- **Description**: Assess if datatype is a bool.

#### `is_string`
- **Signature**: `fn is_string(&self) -> bool`
- **Description**: Assess if datatype is a string.

#### `is_error`
- **Signature**: `fn is_error(&self) -> bool`
- **Description**: Assess if datatype is a `CellErrorType`.

#### `is_duration_iso`
- **Signature**: `fn is_duration_iso(&self) -> bool`
- **Description**: Assess if datatype is an ISO8601 duration.

#### `is_datetime`
- **Signature**: `fn is_datetime(&self) -> bool`
- **Description**: Assess if datatype is a datetime.

#### `is_datetime_iso`
- **Signature**: `fn is_datetime_iso(&self) -> bool`
- **Description**: Assess if datatype is an ISO8601 datetime.

#### `get_int`
- **Signature**: `fn get_int(&self) -> Option<i64>`
- **Description**: Try getting int value.

#### `get_float`
- **Signature**: `fn get_float(&self) -> Option<f64>`
- **Description**: Try getting float value.

#### `get_bool`
- **Signature**: `fn get_bool(&self) -> Option<bool>`
- **Description**: Try getting bool value.

#### `get_string`
- **Signature**: `fn get_string(&self) -> Option<&str>`
- **Description**: Try getting string value.

#### `get_datetime`
- **Signature**: `fn get_datetime(&self) -> Option<ExcelDateTime>`
- **Description**: Try getting datetime value.

#### `get_datetime_iso`
- **Signature**: `fn get_datetime_iso(&self) -> Option<&str>`
- **Description**: Try getting datetime ISO8601 value.

#### `get_duration_iso`
- **Signature**: `fn get_duration_iso(&self) -> Option<&str>`
- **Description**: Try getting duration ISO8601 value.

#### `get_error`
- **Signature**: `fn get_error(&self) -> Option<&CellErrorType>`
- **Description**: Try getting Error value.

#### `as_string`
- **Signature**: `fn as_string(&self) -> Option<String>`
- **Description**: Try converting data type into a string.

#### `as_i64`
- **Signature**: `fn as_i64(&self) -> Option<i64>`
- **Description**: Try converting data type into an int.

#### `as_f64`
- **Signature**: `fn as_f64(&self) -> Option<f64>`
- **Description**: Try converting data type into a float.

#### `as_date` (feature `chrono`)
- **Signature**: `fn as_date(&self) -> Option<chrono::NaiveDate>`
- **Description**: Try converting data type into a date.

#### `as_time` (feature `chrono`)
- **Signature**: `fn as_time(&self) -> Option<chrono::NaiveTime>`
- **Description**: Try converting data type into a time.

#### `as_duration` (feature `chrono`)
- **Signature**: `fn as_duration(&self) -> Option<chrono::Duration>`
- **Description**: Try converting data type into a duration.

#### `as_datetime` (feature `chrono`)
- **Signature**: `fn as_datetime(&self) -> Option<chrono::NaiveDateTime>`
- **Description**: Try converting data type into a datetime.

### Implementations
- Implemented for `Data` and `DataRef<'_>`.

### Conversion Semantics

| Method | `Data::Int` | `Data::Float` | `Data::String` | `Data::Bool` | else |
|--------|-------------|---------------|----------------|--------------|------|
| `as_i64` | `Some(v)` | `Some(v as i64)` | parsed with `atoi_simd` | `Some(0/1)` | `None` |
| `as_f64` | `Some(v as f64)` | `Some(v)` | parsed with `fast_float2` | `Some(0.0/1.0)` | `None` |
| `as_string` | `Some(v.to_string())` | `Some(v.to_string())` | `Some(clone)` | `None` | `None` |
| `is_*`/`get_*` | — | — | — | — | exact-variant matching |

For `DataRef`, `as_i64`/`as_f64`/`as_string`/`is_string`/`get_string` also handle `SharedString`.

### Feature-gated Methods
- `as_date()` — `DateTime`/ISO date extraction (`src/datatype.rs:604`).
- `as_time()` — `DateTime`/ISO time, plus `DurationIso` parsed with `"PT%HH%MM%S%.fS"` (`src/datatype.rs:622`).
- `as_duration()` — `DateTime` via `ExcelDateTime::as_duration`, `DurationIso` via `as_time` (`src/datatype.rs:644`).
- `as_datetime()` — numeric cells (assumed Excel serials), `DateTime`, or `DateTimeIso` parsed with `NaiveDateTime::from_str` (`src/datatype.rs:662`). Numeric serials are converted with the 1900 epoch default (`ExcelDateTime::from_value_only`).

### Example
```rust
use calamine::{Data, DataType};

// DataType methods are available on both Data and DataRef.
let d = Data::Int(42);
assert_eq!(d.as_i64(), Some(42));
assert_eq!(d.as_f64(), Some(42.0));
assert_eq!(d.to_string(), "42");
```

### Example (chrono feature)
```rust
#[cfg(feature = "chrono")]
{
    use calamine::{Data, DataType, ExcelDateTime, ExcelDateTimeType};
    use chrono::NaiveDate;

    // The Unix epoch as an Excel serial date is 25569.0.
    let unix = Data::Float(25569.0);
    assert_eq!(unix.as_datetime().map(|dt| dt.date()),
               Some(NaiveDate::from_ymd_opt(1970, 1, 1).unwrap()));

    let dt = ExcelDateTime::new(25569.0, ExcelDateTimeType::DateTime, false);
    assert!(dt.is_datetime());
    assert_eq!(dt.to_ymd_hms_milli(), (1970, 1, 1, 0, 0, 0, 0));
}
```
```

--------------------------------

### Function signature for deserialize_as_f64_or_none

Source: https://github.com/tafia/calamine/blob/master/_autodocs/api-reference/lib.md

Shows the signature of the `deserialize_as_f64_or_none` helper. It takes a Serde deserializer and returns `Result<Option<f64>, D::Error>`. This is used with `#[serde(deserialize_with = "...")]`.

```rust
pub fn deserialize_as_f64_or_none<'de, D>(deserializer: D) -> Result<Option<f64>, D::Error>
where
    D: Deserializer<'de>,
```
Tokens:
Raw