### Example: Deserialize Range Data in Rust

Source: https://docs.rs/calamine/latest/calamine/struct.RangeDeserializer.html

Demonstrates how to use RangeDeserializer to open an XLSX file, get a specific worksheet range, and iterate over its rows, deserializing each row into a tuple of String and f64. This example requires the `calamine` and `serde` crates.

```Rust
fn main() -> Result<(), Error> {
    let path = format!("{}/tests/temperature.xlsx", env!("CARGO_MANIFEST_DIR"));
    let mut workbook: Xlsx<_> = open_workbook(path)?;
    let range = workbook.worksheet_range("Sheet1")?;

    let mut iter = RangeDeserializerBuilder::new().from_range(&range)?;

    if let Some(result) = iter.next() {
        let (label, value): (String, f64) = result?;
        assert_eq!(label, "celsius");
        assert_eq!(value, 22.2222);
        Ok(())
    } else {
        Err(From::from("expected at least one record but got none"))
    }
}
```

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

### Load and Get All Table Names in Excel Workbook (Rust)

Source: https://docs.rs/calamine/latest/calamine/struct.Xlsx.html?search=

This Rust example shows how to load all tables from an Excel workbook using Calamine and then retrieve their names. It first opens the workbook, explicitly loads the table data using `load_tables()`, and then fetches all table names using `table_names()`. This is useful for iterating through all tables in a workbook. It panics if tables have not been loaded.

```rust
use calamine::{open_workbook, 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 all the table names in the workbook.
    let table_names = workbook.table_names();

    // Check the table names.
    assert_eq!(
        table_names,
        vec!["Inventory", "Pricing", "Sales_Bob", "Sales_Alice"]
    );

    Ok(())
}

```

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

### Xls::new_with_options

Source: https://docs.rs/calamine/latest/calamine/struct.Xls.html?search=std%3A%3Avec

Creates a new Xls instance using provided options to guide the parsing process.

```APIDOC
## `impl<RS: Read + Seek> Xls<RS>`

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

Creates a new instance using `Options` to inform parsing.

#### Parameters

* `reader`: The input source implementing `Read` and `Seek` traits.
* `options`: `XlsOptions` to configure parsing behavior.

#### Returns

A `Result` containing a new `Xls` instance or an `XlsError`.

#### Example
```rust
use calamine::{Xls, XlsOptions};

let mut options = XlsOptions::default();
// ...set options...
let workbook = Xls::new_with_options(reader, options)?;
```
```

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

### Get Range Start Position in Rust

Source: https://docs.rs/calamine/latest/calamine/struct.Range.html?search=

Illustrates how to retrieve the top-left cell's absolute position of a `Range` in Rust using the `start()` method. This method returns an `Option<(u32, u32)>`, providing the `(row, column)` coordinates, or `None` if the range is empty.

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

let range: Range<Data> = Range::new((2, 3), (9, 3));

assert_eq!(range.start(), Some((2, 3)));
```

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

### Get Merged Regions in Excel Workbook by Worksheet (Rust)

Source: https://docs.rs/calamine/latest/calamine/struct.Xlsx.html?search=

This example demonstrates how to open an Excel workbook using Calamine and retrieve the merged regions for each individual worksheet. It requires the `calamine` crate and assumes an Excel file named 'merged_range.xlsx' is available. The output lists the dimensions of merged regions per sheet.

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

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

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

    // Get the names of all the sheets in the workbook.
    let sheet_names = workbook.sheet_names();

    // Load the merged regions in the workbook.
    workbook.load_merged_regions()?;

    for sheet_name in &sheet_names {
        println זיי{sheet_name}: ");

        // Get the merged regions in the current sheet.
        let merged_regions = workbook.merged_regions_by_sheet(sheet_name);

        for (_, _, dimensions) in &merged_regions {
            // Print the dimensions of each merged region.
            println!("    {dimensions:?}");
        }
    }

    Ok(())
}

```

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

### Initialize and Query Calamine Range

Source: https://docs.rs/calamine/latest/calamine/struct.Range.html?search=std%3A%3Avec

Demonstrates how to instantiate a new Range, create an empty Range, and retrieve the start and end coordinates of a defined range.

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

// Create a 8x1 Range.
let range: Range<Data> = Range::new((2, 2), (9, 2));
assert_eq!(range.width(), 1);
assert_eq!(range.height(), 8);

// Create an empty Range
let empty_range: Range<Data> = Range::empty();
assert!(empty_range.is_empty());

// Get start and end positions
let range = Range::new((2, 3), (9, 3));
assert_eq!(range.start(), Some((2, 3)));
assert_eq!(range.end(), Some((9, 3)));
```

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

### Initialize and Query Calamine Range

Source: https://docs.rs/calamine/latest/calamine/struct.Range.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to instantiate a Range using specific coordinates, create an empty range, and retrieve the start and end positions of a defined range.

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

// Create a 8x1 Range.
let range: Range<Data> = Range::new((2, 2), (9, 2));

assert_eq!(range.width(), 1);
assert_eq!(range.height(), 8);
assert_eq!(range.cells().count(), 8);
assert_eq!(range.used_cells().count(), 0);

// Create an empty range
let empty_range: Range<Data> = Range::empty();
assert!(empty_range.is_empty());

// Get boundaries
let range = Range::new((2, 3), (9, 3));
assert_eq!(range.start(), Some((2, 3)));
assert_eq!(range.end(), Some((9, 3)));
```

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

### Get Pictures from Workbook (Rust)

Source: https://docs.rs/calamine/latest/calamine/trait.Reader.html?search=u32+-%3E+bool

This example demonstrates how to retrieve raw picture data from a workbook using the `pictures()` method provided by the `Reader` trait. It iterates through the returned vector of tuples, printing the file extension and size of each picture. This functionality is available when the `picture` feature flag is enabled.

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

// Assuming 'path' is a valid file path to a spreadsheet
// let workbook: Xlsx<_> = open_workbook(path)?;

// if let Some(pics) = workbook.pictures() {
//     for (ext, data) in pics {
//         println!("Type: '{}', Size: {} bytes", ext, data.len());
//     }
// }
```

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

### GET /table/columns

Source: https://docs.rs/calamine/latest/calamine/struct.Table.html?search=u32+-%3E+bool

Retrieves the header names of the table columns.

```APIDOC
## GET /table/columns

### Description
Returns a list of strings representing the column header names of the table.

### Method
GET

### Endpoint
/table/columns

### Response
#### Success Response (200)
- **columns** (Array<String>) - List of column header names.

### Response Example
{
  "columns": ["Item", "Type", "Quantity"]
}
```

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

### GET /tables/load

Source: https://docs.rs/calamine/latest/calamine/struct.Table.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes the loading of table definitions from an Xlsx workbook into memory, enabling subsequent table access methods.

```APIDOC
## POST /tables/load

### Description
Loads all table definitions from the opened Xlsx workbook. This must be called before attempting to access specific tables by name.

### Method
POST

### Endpoint
workbook.load_tables()

### Response
#### Success Response (200)
- **result** (Result<(), Error>) - Returns Ok(()) if tables were loaded successfully.

### Response Example
{
  "status": "success"
}
```

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

### Example: Deserializing Range without Explicit Headers

Source: https://docs.rs/calamine/latest/calamine/struct.RangeDeserializerBuilder.html?search=std%3A%3Avec

Demonstrates building a RangeDeserializer using the default builder and then deserializing the first row into a tuple of (String, f64). It asserts the deserialized values.

```rust
fn main() -> Result<(), Error> {
    let path = format!("{}/tests/temperature.xlsx", env!("CARGO_MANIFEST_DIR"));
    let mut workbook: Xlsx<_> = open_workbook(path)?;
    let range = workbook.worksheet_range("Sheet1")?;
    let mut iter = RangeDeserializerBuilder::new().from_range(&range)?;

    if let Some(result) = iter.next() {
        let (label, value): (String, f64) = result?;
        assert_eq!(label, "celsius");
        assert_eq!(value, 22.2222);

        Ok(())
    } else {
        Err(From::from("expected at least one record but got none"))
    }
}
```

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

### Access Workbook Pictures

Source: https://docs.rs/calamine/latest/calamine/trait.Reader.html

Example of how to extract raw image data from a workbook using the pictures() method. This requires the 'picture' feature flag to be enabled.

```rust
let workbook: Xlsx<_> = open_workbook(path)?;

if let Some(pics) = workbook.pictures() {
    for (ext, data) in pics {
        println!("Type: '{}', Size: {} bytes", ext, data.len());
    }
}
```

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

### Create Xls Instance with Options (Rust)

Source: https://docs.rs/calamine/latest/calamine/struct.Xls.html

Demonstrates how to create a new Xls workbook instance using custom options. This is useful for configuring how the XLS file is parsed, such as specifying header row behavior. It requires the `Xls` and `XlsOptions` types from the calamine crate.

```rust
use calamine::{Xls,XlsOptions};

let mut options = XlsOptions::default();
// ...set options...
let workbook = Xls::new_with_options(reader, options)?;
```

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

### Retrieve Range Coordinates

Source: https://docs.rs/calamine/latest/calamine/struct.Range.html

Examples for accessing the start and end absolute (row, column) positions of a defined Range.

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

let range: Range<Data> = Range::new((2, 3), (9, 3));

assert_eq!(range.start(), Some((2, 3)));
assert_eq!(range.end(), Some((9, 3)));
```

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

### Build Deserializer with Specific Headers

Source: https://docs.rs/calamine/latest/calamine/struct.RangeDeserializerBuilder.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to initialize a deserializer that filters and maps specific columns based on provided header names.

```Rust
fn main() -> Result<(), Error> {
    let path = format!("{}/tests/temperature.xlsx", env!("CARGO_MANIFEST_DIR"));
    let mut workbook: Xlsx<_> = open_workbook(path)?;
    let range = workbook.worksheet_range("Sheet1")?;
    let mut iter = RangeDeserializerBuilder::with_headers(&["value", "label"]).from_range(&range)?;

    if let Some(result) = iter.next() {
        let (value, label): (f64, String) = result?;
        assert_eq!(label, "celsius");
        assert_eq!(value, 22.2222);
        Ok(())
    } else {
        Err(From::from("expected at least one record but got none"))
    }
}
```

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

### Initialize Xls Workbook with Options

Source: https://docs.rs/calamine/latest/calamine/struct.Xls.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to create a new instance of the Xls struct using custom parsing options. This requires a reader that implements Read and Seek traits.

```rust
use calamine::{Xls, XlsOptions};

let mut options = XlsOptions::default();
// ...set options...
let workbook = Xls::new_with_options(reader, options)?;
```

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

### Get Calamine Range Height

Source: https://docs.rs/calamine/latest/calamine/struct.Range.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the row height of a Calamine Range. The height is calculated as the number of rows between the start and end positions of the range.

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

let range: Range<Data> = Range::new((2, 3), (9, 3));

assert_eq!(range.height(), 8);
```

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

### POST /xls/new

Source: https://docs.rs/calamine/latest/calamine/struct.Xls.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes a new Xls workbook reader instance with optional parsing configurations.

```APIDOC
## POST /xls/new

### Description
Creates a new instance of the Xls reader to process legacy Excel files. It accepts a reader and optional configuration settings.

### Method
POST

### Endpoint
/xls/new

### Parameters
#### Request Body
- **reader** (RS) - Required - A type implementing Read + Seek traits.
- **options** (XlsOptions) - Optional - Configuration settings for parsing the workbook.

### Request Example
{
  "reader": "<FileStream>",
  "options": {
    "default": true
  }
}

### Response
#### Success Response (200)
- **workbook** (Xls) - An initialized Xls workbook instance.

#### Response Example
{
  "status": "success",
  "message": "Workbook initialized"
}
```

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

### Get Calamine Range Width

Source: https://docs.rs/calamine/latest/calamine/struct.Range.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the column width of a Calamine Range. The width is calculated as the number of columns between the start and end positions of the range.

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

let range: Range<Data> = Range::new((2, 3), (9, 3));

assert_eq!(range.width(), 1);
```

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

### POST /xls/new

Source: https://docs.rs/calamine/latest/calamine/struct.Xls.html?search=u32+-%3E+bool

Creates a new instance of the Xls parser with optional configuration.

```APIDOC
## POST /xls/new

### Description
Initializes a new Xls parser instance using a reader and optional configuration settings.

### Method
POST

### Endpoint
/xls/new

### Parameters
#### Request Body
- **reader** (RS) - Required - The source reader (must implement Read + Seek).
- **options** (XlsOptions) - Optional - Configuration options for parsing.

### Request Example
{
  "options": { "default": true }
}

### Response
#### Success Response (200)
- **instance** (Xls) - The initialized Xls parser instance.

#### Response Example
{
  "status": "success",
  "instance_id": "xls_001"
}
```

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

### Rust: Get Excel Table Name with Calamine

Source: https://docs.rs/calamine/latest/calamine/struct.Table.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to retrieve the name of an Excel worksheet table using the calamine crate in Rust. This example assumes the workbook and table have already been loaded.

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

fn main() -> Result<(), Error> {
    let path = format!("{}/tests/inventory-table.xlsx", env!("CARGO_MANIFEST_DIR"));

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

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

    // Get the table by name.
    let table = workbook.table_by_name("Table1")?;

    // Check the table's name.
    let table_name = table.name();
    assert_eq!(table_name, "Table1");

    Ok(())
}
```

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

### POST /xls/new

Source: https://docs.rs/calamine/latest/calamine/struct.Xls.html?search=

Initializes a new Xls reader instance for processing Excel files.

```APIDOC
## POST /xls/new

### Description
Creates a new instance of the Xls reader to parse a CFB-based Excel file.

### Method
POST

### Endpoint
/xls/new

### Parameters
#### Request Body
- **reader** (Read + Seek) - Required - The input stream of the Excel file.
- **options** (XlsOptions) - Optional - Configuration options for parsing.

### Request Example
{
  "reader": "<stream>",
  "options": { "default": true }
}

### Response
#### Success Response (200)
- **instance** (Xls) - The initialized Xls reader object.

#### Response Example
{
  "status": "success",
  "message": "Xls reader initialized"
}
```

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

### Get Table Names in Excel Workbook by Worksheet (Rust)

Source: https://docs.rs/calamine/latest/calamine/struct.Xlsx.html?search=

This Rust example demonstrates how to retrieve the names of tables present within a specific worksheet of an Excel workbook using Calamine. After opening the workbook and loading table data, it iterates through each sheet, calling `table_names_in_sheet()` to get the tables for that particular sheet. This method is essential for understanding the tabular structure of individual worksheets. It panics if tables have not been loaded.

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

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

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

    // Get the names of all the sheets in the workbook.
    let sheet_names = workbook.sheet_names();

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

    for sheet_name in &sheet_names {
        // Get the table names in the current sheet.
        let table_names = workbook.table_names_in_sheet(sheet_name);

        // Print the associated table names.
        println זיי{sheet_name} contains tables: {table_names:?}");
    }

    Ok(())
}

```

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

### Get Merged Cells by Sheet Name in Excel using Calamine

Source: https://docs.rs/calamine/latest/calamine/struct.Xlsx.html?search=

This example demonstrates how to open an Excel workbook and iterate through its worksheets to retrieve and print the dimensions of all merged cell regions within each sheet. It utilizes the `open_workbook` function and the `worksheet_merge_cells` method.

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

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

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

    // Get the names of all the sheets in the workbook.
    let sheet_names = workbook.sheet_names();

    for sheet_name in &sheet_names {
        println!("{sheet_name}: ");

        // Get the merged cells in the current sheet.
        let merge_cells = workbook.worksheet_merge_cells(sheet_name);

        if let Some(dimensions) = merge_cells {
            let dimensions = dimensions?;

            // Print the dimensions of each merged region.
            for dimension in &dimensions {
                println!("    {dimension:?}");
            }
        }
    }

    Ok(())
}

```

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

### Xls::new_with_options

Source: https://docs.rs/calamine/latest/calamine/struct.Xls.html

Creates a new Xls instance with specified options for parsing.

```APIDOC
## `new_with_options`

### Description
Creates a new instance using `Options` to inform parsing.

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

### Parameters
- **reader** (RS): A type that implements `Read` and `Seek` traits, representing the XLS file source.
- **options** (XlsOptions): Options to configure the XLS parsing behavior.

### Returns
- `Result<Self, XlsError>`: A `Result` containing the `Xls` instance on success or an `XlsError` on failure.

### Request Example
```rust
use calamine::{Xls, XlsOptions};

let mut options = XlsOptions::default();
// ...set options...
let workbook = Xls::new_with_options(reader, options)?;
```
```

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

### Get Merged Cells by Sheet Index in Excel using Calamine

Source: https://docs.rs/calamine/latest/calamine/struct.Xlsx.html?search=

This example shows how to open an Excel workbook and retrieve the merged cell regions from a specific worksheet using its zero-based index. It uses the `open_workbook` function and the `worksheet_merge_cells_at` method, returning a vector of `Dimensions`.

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

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

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

    // Get the merged cells in the first worksheet.
    let merge_cells = workbook.worksheet_merge_cells_at(0);

    if let Some(dimensions) = merge_cells {
        let dimensions = dimensions?;

        // Print the dimensions of each merged region.
        for dimension in &dimensions {
            println!("{dimension:?}");
        }
    }

    Ok(())
}

```

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

### Get Worksheet Cell Reader in Excel with Calamine

Source: https://docs.rs/calamine/latest/calamine/struct.Xlsx.html?search=u32+-%3E+bool

This example demonstrates how to obtain a reader for all used cells within a specific worksheet of an Excel file using the Calamine library. The `worksheet_cells_reader` function returns a `XlsxCellReader` which can be used to iterate over the cells. This is useful for processing cell data efficiently.

```rust
pub fn worksheet_cells_reader<'a>(
    &'a mut self,
    name: &str,
) -> Result<XlsxCellReader<'a, RS>, XlsxError>

```

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

### Configure Range Deserialization with Headers

Source: https://docs.rs/calamine/latest/calamine/struct.RangeDeserializerBuilder.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to use RangeDeserializerBuilder to toggle header row parsing and iterate through spreadsheet data.

```Rust
fn main() -> Result<(), Error> {
    let path = format!("{}/tests/temperature.xlsx", env!("CARGO_MANIFEST_DIR"));
    let mut workbook: Xlsx<_> = open_workbook(path)?;
    let range = workbook.worksheet_range("Sheet1")?;

    let mut iter = RangeDeserializerBuilder::new()
        .has_headers(false)
        .from_range(&range)?;

    if let Some(result) = iter.next() {
        let row: Vec<Data> = result?;
        assert_eq!(row, [Data::from("label"), Data::from("value")]);
    } else {
        return Err(From::from("expected at least three records but got none"));
    }

    Ok(())
}
```

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

### Get Pictures from Workbook (Rust)

Source: https://docs.rs/calamine/latest/calamine/trait.Reader.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This example demonstrates how to retrieve raw picture data from a workbook using the `pictures()` method provided by the `Reader` trait. It iterates through the returned vector of (file extension, image data) tuples and prints their type and size. This functionality is available when the `picture` feature flag is enabled.

```rust
use calamine::Xlsx;
use calamine::Reader;

// Assuming 'path' is a valid file path to a spreadsheet
// let workbook: Xlsx<_> = open_workbook(path)?;

// if let Some(pics) = workbook.pictures() {
//     for (ext, data) in pics {
//         println!("Type: '{}', Size: {} bytes", ext, data.len());
//     }
// }
```

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

### Configure Range Deserialization with Headers

Source: https://docs.rs/calamine/latest/calamine/struct.RangeDeserializerBuilder.html

Demonstrates how to use RangeDeserializerBuilder to toggle header row processing and iterate through spreadsheet data.

```rust
fn main() -> Result<(), Error> {
    let path = format!("{}/tests/temperature.xlsx", env!("CARGO_MANIFEST_DIR"));
    let mut workbook: Xlsx<_> = open_workbook(path)?;
    let range = workbook.worksheet_range("Sheet1")?;

    let mut iter = RangeDeserializerBuilder::new()
        .has_headers(false)
        .from_range(&range)?;

    if let Some(result) = iter.next() {
        let row: Vec<Data> = result?;
        assert_eq!(row, [Data::from("label"), Data::from("value")]);
    }
    Ok(())
}
```

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

### Enable Calamine Crate Features

Source: https://docs.rs/calamine/latest/calamine/index.html

Shows how to enable optional features such as 'chrono' for date/time support in the Cargo.toml file.

```TOML
cargo add calamine -F chrono
```

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

### Example: Reading VBA Modules with Calamine

Source: https://docs.rs/calamine/latest/calamine/vba/struct.VbaProject.html?search=

Demonstrates how to use the `calamine` crate to open an Excel file, access its VBA project, retrieve module names, and print the content of each module. It shows error handling for file opening and module reading.

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

let mut xl: Xlsx<_> = open_workbook(path).expect("Cannot find excel file");
if let Ok(Some(vba)) = xl.vba_project() {
    let modules = vba.get_module_names().into_iter()
                     .map(|s| s.to_string()).collect::<Vec<_>>();
    for m in modules {
        println!("Module {m}:");
        println!("{}", vba.get_module(&m)
                          .unwrap_or_else(|_| panic!("cannot read {m:?} module")));
    }
}
```

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

### Get Nth Worksheet Data by Reference with Calamine

Source: https://docs.rs/calamine/latest/calamine/enum.Sheets.html?search=

Explains the `worksheet_range_at_ref` method for the `Sheets` enum, which gets the Nth worksheet's data as a borrowed reference (`Range<DataRef<'_>>`). This method is a shortcut for getting the Nth worksheet by name and then accessing its range by reference.

```rust
fn worksheet_range_at_ref( &mut self, n: usize, ) -> Option<Result<Range<DataRef<'_>>, Self::Error>>
```

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

### Get Xlsx Worksheet Range by Index

Source: https://docs.rs/calamine/latest/calamine/struct.Xlsx.html

Fetches the nth worksheet as a Range. This is a convenience method that first gets the worksheet's name and then retrieves the corresponding worksheet data. It returns an Option containing a Result, which can be a Range of Data or an error.

```rust
fn worksheet_range_at(&mut self, n: usize) -> Option<Result<Range<Data>, Self::Error>>
```

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

### Create VbaProject Instance

Source: https://docs.rs/calamine/latest/calamine/vba/struct.VbaProject.html?search=

Constructs a new `VbaProject` instance by reading the VBA project metadata from a given `Read` source, such as a `ZipFile` or an xls file. It handles the initial parsing of headers, directories, and sectors.

```rust
pub fn new<R: Read>(r: &mut R, len: usize) -> Result<VbaProject, VbaError>
```

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

### GET /vba_project

Source: https://docs.rs/calamine/latest/calamine/struct.Ods.html?search=u32+-%3E+bool

Attempts to extract the VBA project associated with the spreadsheet.

```APIDOC
## GET /vba_project

### Description
Retrieves the VbaProject object if one exists within the Ods document.

### Method
GET

### Endpoint
/vba_project

### Response
#### Success Response (200)
- **project** (Option<VbaProject>) - The VBA project data if present.

#### Response Example
{
  "project": null
}
```

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

### Open Excel Workbook with open_workbook

Source: https://docs.rs/calamine/latest/calamine/fn.open_workbook.html

This function initializes a workbook reader from a given file path. It requires the path to implement AsRef<Path> and returns a Result containing the reader or an error.

```rust
pub fn open_workbook<R, P>(path: P) -> Result<R, R::Error>
where
    R: Reader<BufReader<File>>,
    P: AsRef<Path>,
```

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

### GET /sheet_names

Source: https://docs.rs/calamine/latest/calamine/struct.Ods.html?search=u32+-%3E+bool

Retrieves a list of all sheet names present in the workbook.

```APIDOC
## GET /sheet_names

### Description
Returns an ordered list of all sheet names available in the Ods workbook.

### Method
GET

### Endpoint
/sheet_names

### Response
#### Success Response (200)
- **names** (array of strings) - List of sheet names.

#### Response Example
{
  "names": ["Sheet1", "Sheet2", "Summary"]
}
```

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

### Initialize and Read Xlsb Worksheets

Source: https://docs.rs/calamine/latest/calamine/struct.Xlsb.html

Demonstrates how to instantiate an Xlsb reader and access worksheet data. The reader requires a type that implements Read and Seek traits.

```rust
use calamine::{Xlsb, Reader};
use std::fs::File;
use std::io::BufReader;

// Initialize the reader
let file = File::open("workbook.xlsb").unwrap();
let mut reader = Xlsb::new(BufReader::new(file)).unwrap();

// Access worksheet data
if let Ok(range) = reader.worksheet_range("Sheet1") {
    for row in range.rows() {
        println!("{:?}", row);
    }
}
```

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

### Initialize memory with CloneToUninit

Source: https://docs.rs/calamine/latest/calamine/struct.Table.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The CloneToUninit trait provides an experimental nightly-only method to perform copy-assignment from a source to an uninitialized memory destination. It is intended for low-level memory operations where direct initialization is required.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8);
```

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

### GET /worksheet_range

Source: https://docs.rs/calamine/latest/calamine/struct.Ods.html?search=u32+-%3E+bool

Retrieves the data range from a specific worksheet by its name.

```APIDOC
## GET /worksheet_range

### Description
Reads the data contained within a specific worksheet identified by its name.

### Method
GET

### Endpoint
/worksheet_range

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

### Request Example
{
  "name": "Sheet1"
}

### Response
#### Success Response (200)
- **Range<Data>** (object) - The parsed data range of the worksheet.

#### Response Example
{
  "range": "[[Data, Data], [Data, Data]]"
}
```

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

### Get Xlsx Worksheet Range by Index (Borrowed)

Source: https://docs.rs/calamine/latest/calamine/struct.Xlsx.html

Fetches the nth worksheet range, borrowing shared string values. Similar to `worksheet_range_at`, this method provides a shortcut by getting the worksheet name first, then returning a Range of DataRef. It returns an Option containing a Result.

```rust
fn worksheet_range_at_ref(&mut self, n: usize) -> Option<Result<Range<DataRef<'_>>, Self::Error>>
```

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

### Open Workbook from Reader in Rust

Source: https://docs.rs/calamine/latest/calamine/fn.open_workbook_auto_from_rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes a workbook reader from a data source that implements the Read, Seek, and Clone traits. It is recommended to use the statically known open_workbook_from_rs function when possible for better performance and type safety.

```rust
pub fn open_workbook_auto_from_rs<RS>(data: RS) -> Result<Sheets<RS>, Error>
where
    RS: Read + Seek + Clone,
```

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

### Implement TryFrom and TryInto traits for generic types

Source: https://docs.rs/calamine/latest/calamine/struct.RangeDeserializer.html?search=

These traits allow for safe, fallible conversions between types. TryFrom defines the conversion logic from a source type, while TryInto provides a method to perform the conversion into a target type.

```rust
impl<T, U> TryFrom<U> for T where U: Into<T> {
	type Error = Infallible;
	fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> {
		Ok(value.into())
	}
}

impl<T, U> TryInto<U> for T where U: TryFrom<T> {
	type Error = <U as TryFrom<T>>::Error;
	fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error> {
		U::try_from(self)
	}
}
```

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

### GET worksheet_range

Source: https://docs.rs/calamine/latest/calamine/struct.Xlsx.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Reads the data contained within a specific worksheet.

```APIDOC
## GET worksheet_range

### Description
Reads all data from a worksheet specified by name and returns it as a Range object.

### Method
GET

### Endpoint
workbook.worksheet_range(name: &str)

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

### Response
#### Success Response (200)
- **range** (Range<Data>) - The data contained in the worksheet.
```

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

### Initialize Xlsb reader

Source: https://docs.rs/calamine/latest/calamine/struct.Xlsb.html?search=

Creates a new instance of the Xlsb reader from a provided reader source.

```rust
fn new(reader: RS) -> Result<Self, XlsbError>
```

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

### GET /xls/sheet_names

Source: https://docs.rs/calamine/latest/calamine/struct.Xls.html?search=u32+-%3E+bool

Lists all sheet names present in the workbook.

```APIDOC
## GET /xls/sheet_names

### Description
Returns a list of all sheet names in the workbook in their defined order.

### Method
GET

### Endpoint
/xls/sheet_names

### Response
#### Success Response (200)
- **names** (Vec<String>) - A list of sheet names.

#### Response Example
{
  "names": ["Sheet1", "Sheet2", "Summary"]
}
```

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

### GET /table/data

Source: https://docs.rs/calamine/latest/calamine/struct.Table.html?search=u32+-%3E+bool

Retrieves the data range of the table, excluding headers.

```APIDOC
## GET /table/data

### Description
Returns the data range of the table. Note that the returned range excludes the column headers.

### Method
GET

### Endpoint
/table/data

### Response
#### Success Response (200)
- **data** (Range) - The range object containing table data.

### Response Example
{
  "data": {
    "rows": [["Apple", "Fruit", "10"]]
  }
}
```

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

### Initialize Xlsb reader

Source: https://docs.rs/calamine/latest/calamine/struct.Xlsb.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new instance of the Xlsb reader from a provided source that implements Read and Seek.

```rust
impl<RS: Read + Seek> Xlsb<RS> {
	pub fn new(reader: RS) -> Result<Self, XlsbError> { /* ... */ }
}
```

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

### Rust Blanket Implementations: Borrow and BorrowMut Traits

Source: https://docs.rs/calamine/latest/calamine/struct.RangeDeserializerBuilder.html?search=std%3A%3Avec

Illustrates the blanket implementations of Borrow and BorrowMut traits for any type T. These traits allow for immutable and mutable borrowing, respectively, enabling flexible data access patterns.

```rust
impl<T> Borrow<T> for T
where
    T: ?Sized,
{
    fn borrow(&self) -> &T;
}

impl<T> BorrowMut<T> for T
where
    T: ?Sized,
{
    fn borrow_mut(&mut self) -> &mut T;
}
```

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

### GET /iterator/max

Source: https://docs.rs/calamine/latest/calamine/struct.UsedCells.html?search=std%3A%3Avec

Retrieves the maximum element from the iterator based on the Ord trait.

```APIDOC
## GET /iterator/max

### Description
Returns the maximum element of an iterator.

### Method
GET

### Endpoint
/iterator/max

### Response
#### Success Response (200)
- **item** (Option<Item>) - The maximum element found in the iterator.
```

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

### GET /iterator/find

Source: https://docs.rs/calamine/latest/calamine/struct.UsedCells.html?search=std%3A%3Avec

Searches for the first element in the iterator that satisfies the provided predicate.

```APIDOC
## GET /iterator/find

### Description
Searches for an element of an iterator that satisfies a predicate.

### Method
GET

### Endpoint
/iterator/find

### Parameters
#### Query Parameters
- **predicate** (FnMut) - Required - Function to test elements

### Response
#### Success Response (200)
- **item** (Option<Item>) - The first element matching the predicate, or None.
```

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

### Rust Blanket Implementations: From and Into Traits

Source: https://docs.rs/calamine/latest/calamine/struct.RangeDeserializerBuilder.html?search=std%3A%3Avec

Details the blanket implementations of the From and Into traits. From<T> for T allows conversion into a type, while Into<U> for T leverages From<T> for U to enable conversion from T to U.

```rust
impl<T> From<T> for T {
    fn from(t: T) -> T;
}

impl<T, U> Into<U> for T
where
    U: From<T>,
{
    fn into(self) -> U;
}
```

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

### GET /xls/worksheet/merge-cells

Source: https://docs.rs/calamine/latest/calamine/struct.Xls.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Fetches the dimensions of merged cells for a specific worksheet.

```APIDOC
## GET /xls/worksheet/merge-cells

### Description
Returns a list of dimensions for all merged cells found in the specified worksheet.

### Method
GET

### Endpoint
/xls/worksheet/merge-cells

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

### Response
#### Success Response (200)
- **dimensions** (Vec<Dimensions>) - A list of merged cell coordinate ranges.

#### Response Example
{
  "merge_cells": [
    {"start": [0, 0], "end": [0, 2]}
  ]
}
```

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

### Create New RangeDeserializerBuilder

Source: https://docs.rs/calamine/latest/calamine/struct.RangeDeserializerBuilder.html?search=std%3A%3Avec

Constructs a new RangeDeserializerBuilder instance with default settings. This builder is used to configure options before creating a RangeDeserializer.

```rust
pub fn new() -> Self
```

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

### GET /xls/worksheet_range

Source: https://docs.rs/calamine/latest/calamine/struct.Xls.html?search=u32+-%3E+bool

Retrieves the data range from a specific worksheet by name.

```APIDOC
## GET /xls/worksheet_range

### Description
Reads and returns the data contained within a specified worksheet.

### Method
GET

### Endpoint
/xls/worksheet_range

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

### Request Example
{
  "name": "Sheet1"
}

### Response
#### Success Response (200)
- **data** (Range<Data>) - The worksheet content.

#### Response Example
{
  "data": [["Header1", "Header2"], [1, 2]]
}
```

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

### Create and Iterate over Cell Ranges in Rust

Source: https://docs.rs/calamine/latest/calamine/struct.Cell.html?search=std%3A%3Avec

Demonstrates how to initialize a collection of Cell objects, construct a Range from them, and iterate through the resulting grid.

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

let cells = vec![
    Cell::new((1, 1), Data::Int(1)),
    Cell::new((1, 2), Data::Int(2)),
    Cell::new((3, 1), Data::Int(3)),
];

// Create a Range from the cells.
let range = Range::from_sparse(cells);

// Iterate over the cells in the range.
for (row, col, data) in range.cells() {
    println!("({row}, {col}): {data}");
}
```

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

### GET /table/sheet_name

Source: https://docs.rs/calamine/latest/calamine/struct.Table.html?search=u32+-%3E+bool

Retrieves the name of the parent worksheet for a specific Excel table.

```APIDOC
## GET /table/sheet_name

### Description
Returns the name of the worksheet where the table is located.

### Method
GET

### Endpoint
/table/sheet_name

### Response
#### Success Response (200)
- **sheet_name** (String) - The name of the worksheet.

### Response Example
{
  "sheet_name": "Sheet1"
}
```

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

### Blanket Implementations

Source: https://docs.rs/calamine/latest/calamine/struct.RangeDeserializerBuilder.html

Standard Rust blanket implementations available for types within the Calamine crate.

```APIDOC
## Blanket Implementations

### Description
Common Rust traits implemented for all types `T` that satisfy specific bounds.

### Available Traits
- **Any**: Provides `type_id()` for runtime type identification.
- **Borrow/BorrowMut**: Provides `borrow()` and `borrow_mut()` for flexible reference handling.
- **CloneToUninit**: Experimental API for uninitialized memory copying.
- **From/Into**: Standard conversion traits.
- **ToOwned**: Provides `to_owned()` and `clone_into()` for cloning borrowed data.
- **TryFrom/TryInto**: Fallible conversion traits.
```

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

### GET /dimensions/contains

Source: https://docs.rs/calamine/latest/calamine/struct.RangeDeserializer.html?search=u32+-%3E+bool

Checks if a specific coordinate position exists within the defined dimensions.

```APIDOC
## GET /dimensions/contains

### Description
Checks if a given (row, column) position is contained within the current Dimensions object.

### Method
GET

### Parameters
#### Query Parameters
- **row** (u32) - Required - The row index to check.
- **col** (u32) - Required - The column index to check.

### Response
#### Success Response (200)
- **result** (bool) - Returns true if the position is within bounds, false otherwise.

### Response Example
{
  "result": true
}
```

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

### Generic Blanket Implementations for Rust Types

Source: https://docs.rs/calamine/latest/calamine/vba/struct.Reference.html?search=

Demonstrates common blanket implementations that apply to many Rust types, including `Any`, `Borrow`, `BorrowMut`, `CloneToUninit`, `Equivalent`, `From`, `Into`, `ToOwned`, `TryFrom`, and `TryInto`. These are often provided by the standard library or common crates.

```rust
impl<T> Any for T where T: 'static + ?Sized {
    fn type_id(&self) -> TypeId
}

impl<T> Borrow<T> for T where T: ?Sized {
    fn borrow(&self) -> &T
}

// ... other blanket implementations
```

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

### GET /dimensions/contains

Source: https://docs.rs/calamine/latest/calamine/fn.deserialize_as_date_or_none.html?search=u32+-%3E+bool

Checks if a specific coordinate pair exists within the defined dimensions.

```APIDOC
## [METHOD] Dimensions::contains

### Description
Checks if a given row and column position is contained within the current `Dimensions` object.

### Method
Method Call

### Parameters
#### Arguments
- **row** (u32) - Required - The row index to check.
- **col** (u32) - Required - The column index to check.

### Response
- **bool** - Returns `true` if the position is within bounds, otherwise `false`.
```

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

### CloneToUninit Trait

Source: https://docs.rs/calamine/latest/calamine/struct.Table.html

The `CloneToUninit` trait allows for copy-assignment from `self` to an uninitialized memory location. This is an experimental, nightly-only API.

```APIDOC
## unsafe fn clone_to_uninit(&self, dest: *mut u8)

### Description
Performs copy-assignment from `self` to `dest`. This is a nightly-only experimental API.

### Method
`unsafe fn clone_to_uninit`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

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

### GET /worksheets

Source: https://docs.rs/calamine/latest/calamine/enum.Sheets.html

Fetches all worksheet data and their associated paths from the workbook.

```APIDOC
## GET /worksheets

### Description
Fetch all worksheet data and paths available in the workbook.

### Method
GET

### Endpoint
/worksheets

### Response
#### Success Response (200)
- **worksheets** (Vec<(String, Range<Data>)>) - A list of tuples containing the sheet name and its data range.

#### Response Example
{
  "worksheets": [
    ["Sheet1", [["A1", "B1"]]],
    ["Sheet2", [["A2", "B2"]]]
  ]
}
```

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

### GET worksheet_merge_cells_at

Source: https://docs.rs/calamine/latest/calamine/struct.Xlsx.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the merged cells or regions in a specific worksheet by its zero-based index.

```APIDOC
## GET worksheet_merge_cells_at

### Description
Retrieves merged cell regions for a worksheet identified by its index in the workbook.

### Method
GET

### Endpoint
workbook.worksheet_merge_cells_at(sheet_index: usize)

### Parameters
#### Path Parameters
- **sheet_index** (usize) - Required - The zero-based index of the worksheet.

### Request Example
workbook.worksheet_merge_cells_at(0)

### Response
#### Success Response (200)
- **dimensions** (Option<Result<Vec<Dimensions>, XlsxError>>) - A list of merged region coordinates.

#### Response Example
[
  { "start": [0, 7], "end": [1, 7] }
]
```

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

### Perform Type Conversions with From, Into, TryFrom, and TryInto

Source: https://docs.rs/calamine/latest/calamine/struct.Table.html?search=u32+-%3E+bool

These traits define standard patterns for type conversion. From and Into provide infallible conversions, while TryFrom and TryInto handle fallible conversions returning a Result type.

```rust
fn from(t: T) -> T { t }
fn into(self) -> U { U::from(self) }
fn try_from(value: U) -> Result<T, Self::Error>
fn try_into(self) -> Result<U, Self::Error>
```

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

### GET /worksheet_range

Source: https://docs.rs/calamine/latest/calamine/trait.Reader.html?search=std%3A%3Avec

Retrieves the data contained within a specific worksheet by its name.

```APIDOC
## GET /worksheet_range

### Description
Reads the data from a worksheet identified by its name and returns it as a Range of Data.

### Method
GET

### Endpoint
/worksheet_range

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

### Response
#### Success Response (200)
- **Range<Data>** (object) - The data contained within the requested worksheet.

#### Response Example
{
  "range": "[[Data(Int(1)), Data(String(\"Header\"))], [Data(Int(2)), Data(String(\"Value\"))]]"
}
```

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

### Access Table Column Headers

Source: https://docs.rs/calamine/latest/calamine/struct.Table.html?search=std%3A%3Avec

Shows how to extract the header names of table columns as a slice of strings using the columns() method.

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

fn main() -> Result<(), Error> {
    let path = format!("{}/tests/inventory-table.xlsx", env!("CARGO_MANIFEST_DIR"));
    let mut workbook: Xlsx<_> = open_workbook(path)?;
    workbook.load_tables()?;
    let table = workbook.table_by_name("Table1")?;
    let columns_headers = table.columns();
    assert_eq!(columns_headers, vec!["Item", "Type", "Quantity"]);
    Ok(())
}
```

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

### Stateful Iteration and Windowing

Source: https://docs.rs/calamine/latest/calamine/struct.RangeDeserializer.html?search=

Advanced iteration techniques involving internal state and processing elements in contiguous windows.

```APIDOC
## Iterator Adapters: Stateful and Windowing

### Description
These methods provide advanced iteration capabilities, including maintaining internal state during iteration and processing elements in fixed-size windows.

### Methods

#### `scan<St, B, F>(self, initial_state: St, f: F)`
- **Description**: An iterator adapter that holds internal state and produces a new iterator based on that state and the input elements.
- **Method**: `scan`
- **Parameters**:
  - `initial_state` (St) - The initial state for the iterator.
  - `f` (FnMut(&mut St, Self::Item) -> Option<B>) - The closure to update state and produce output.

#### `map_windows<F, R, const N: usize>(self, f: F)`
- **Description**: Calls a function `f` for each contiguous window of size `N` over the iterator's elements and returns an iterator over the results. This is an experimental API.
- **Method**: `map_windows`
- **Parameters**: `f` (FnMut(&[Self::Item; N]) -> R) - The function to apply to each window.
- **Constraints**: Requires nightly Rust. `N` is a const generic specifying the window size.
```

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

### Xls::worksheet_merge_cells_at

Source: https://docs.rs/calamine/latest/calamine/struct.Xls.html?search=std%3A%3Avec

Gets the merge cell dimensions for the nth worksheet by its index.

```APIDOC
## `impl<RS: Read + Seek> Xls<RS>`

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

Get the nth worksheet. Shortcut for getting the nth sheet name, then the corresponding worksheet.

#### Parameters

* `n`: The index of the worksheet.

#### Returns

An `Option` containing a `Vec` of `Dimensions` if merge cells are found for the specified worksheet, otherwise `None`.
```

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

### Rust Blanket Implementations: TryFrom and TryInto Traits

Source: https://docs.rs/calamine/latest/calamine/struct.RangeDeserializerBuilder.html?search=std%3A%3Avec

Explains the blanket implementations of TryFrom and TryInto traits. TryFrom<U> for T allows fallible conversion from U to T, while TryInto<U> for T uses TryFrom<T> for U to enable fallible conversion from T to U.

```rust
use std::convert::Infallible;

impl<T, U> TryFrom<U> for T
where
    U: Into<T>,
{
    type Error = Infallible;
    fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>;
}

impl<T, U> TryInto<U> for T
where
    U: TryFrom<T>,
{
    type Error = <U as TryFrom<T>>::Error;
    fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>;
}
```

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

### GET /iterator/search

Source: https://docs.rs/calamine/latest/calamine/struct.Rows.html

Methods for searching, finding, and testing elements within an iterator.

```APIDOC
## GET /iterator/find

### Description
Searches for the first element of an iterator that satisfies a provided predicate.

### Method
GET

### Endpoint
/iterator/find

### Parameters
#### Query Parameters
- **predicate** (Function) - Required - The condition to test each element against.

### Response
#### Success Response (200)
- **result** (Option<Item>) - The first matching element, if found.
```