### Install umya-spreadsheet

Source: https://github.com/mathnya/umya-spreadsheet/blob/master/README.md

Add the umya-spreadsheet crate to your Cargo.toml. Features like WebAssembly support or specific image formats can be enabled.

```toml
[dependencies]
umya-spreadsheet = "2.2.0"

# WebAssembly support
umya-spreadsheet = { version = "2.2.0", features = ["js"] }

# Use only png for image processing
umya-spreadsheet = { version = "2.2.0", features = ["image/png"] }
```

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

### Retrieve Cell Values by Sheet-Qualified Address

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Gets a list of `CellValue` references using an address string that includes the sheet name (e.g., "SheetName!A1:C5"). This allows fetching data from specific sheets within a workbook.

```rust
use umya_spreadsheet::*

let mut book = new_file();
book.sheet_mut(0).unwrap().cell_mut("A1").set_value("alpha");
book.sheet_mut(0).unwrap().cell_mut("A2").set_value("beta");

let values = book.cell_value_by_address("Sheet1!A1:A2");
for cv in &values {
    println!("{}", cv.value());
}
// Output:
// alpha
// beta
```

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

### Insert and Remove Columns in Workbook

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Inserts or removes columns by letter name or numeric index, automatically adjusting all coordinates and formula references. Specify the sheet name, starting column identifier, and the number of columns to affect.

```rust
use umya_spreadsheet::*

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();
sheet.cell_mut("A1").set_value("Col A");
sheet.cell_mut("B1").set_value("Col B");

// Insert 1 blank column before column B
book.insert_new_column("Sheet1", "B", 1);
// "Col B" is now in C1

// Or use the index variant (column B = index 2)
book.insert_new_column_by_index("Sheet1", 2, 1);

// Remove 2 columns starting at column F
book.remove_column("Sheet1", "F", 2);
book.remove_column_by_index("Sheet1", 6, 2);
```

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

### Read Cell Values as String or Number

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Use `value` to get the string representation of a cell's content. For numeric cells, `value_number` returns an `Option<f64>`. Coordinates can be specified as "A1" strings or (column, row) tuples.

```rust
use umya_spreadsheet::*

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();
sheet.cell_mut("A1").set_value("42.5");
sheet.cell_mut("B1").set_value("hello");

let sheet = book.sheet(0).unwrap();

let str_val: String = sheet.value("A1");      // "42.5"
let num_val: Option<f64> = sheet.value_number("A1"); // Some(42.5)
let str_b1: String = sheet.value((2, 1));     // "hello"

println!("{str_val}, {num_val:?}, {str_b1}");
```

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

### Insert and Remove Rows in Workbook

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Inserts or removes rows within a specified sheet, automatically adjusting all cell coordinates and formula references. Specify the sheet name, starting row index, and the number of rows to affect.

```rust
use umya_spreadsheet::*

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();
sheet.cell_mut("A1").set_value("Row 1");
sheet.cell_mut("A2").set_value("Row 2");
sheet.cell_mut("A3").set_value("Row 3");

// Insert 2 blank rows before row 2
book.insert_new_row("Sheet1", 2, 2);
// "Row 2" is now in A4, "Row 3" in A5

// Remove 1 row starting at row 2
book.remove_row("Sheet1", 2, 1);
```

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

### Initialize main.rs

Source: https://github.com/mathnya/umya-spreadsheet/blob/master/README.md

Declare the umya-spreadsheet crate in your main.rs file to begin using its functionalities.

```rust
extern crate umya_spreadsheet;
```

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

### Create and Update Workbook

Source: https://github.com/mathnya/umya-spreadsheet/blob/master/README.md

Demonstrates creating a new workbook, adding a sheet, and updating a cell within that sheet using the `umya_spreadsheet` library.

```rust
let mut book = umya_spreadsheet::new_file();
let _unused =  book.new_sheet("Sheet2");
update_excel(&mut book);

fn update_excel(book:  &mut Workbook) {
   book.get_sheet_by_name_mut("Sheet2").unwrap().get_cell_mut("A1").set_value("Test"); 
}
```

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

### Create a new workbook without any sheets

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Creates a new Workbook with default theme and stylesheet but no worksheets. At least one sheet must be added before writing the file.

```rust
use umya_spreadsheet::*

let mut book = new_file_empty_worksheet();
let _ = book.new_sheet("Report");
let _ = book.new_sheet("Summary");
```

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

### Create a new workbook with a default sheet

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Creates a new Workbook with a default theme, stylesheet, and one worksheet named "Sheet1". The active cell is set to "A1".

```rust
use umya_spreadsheet::*

let mut book = new_file();

// The workbook already has "Sheet1"
let sheet = book.sheet(0).unwrap();
assert_eq!(sheet.name(), "Sheet1");
```

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

### Create New XLSX File

Source: https://github.com/mathnya/umya-spreadsheet/blob/master/README.md

Initializes a new, empty XLSX file structure in memory.

```rust
let mut book = umya_spreadsheet::new_file();
```

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

### new_file

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Creates a new Workbook with a default theme, stylesheet, and one worksheet named "Sheet1". The active cell is set to "A1".

```APIDOC
## new_file — Create a new workbook

Creates a new `Workbook` with a default theme, stylesheet, and one worksheet named `"Sheet1"` with the active cell set to `"A1"`.

```rust
use umya_spreadsheet::*

let mut book = new_file();

// The workbook already has "Sheet1"
let sheet = book.sheet(0).unwrap();
assert_eq!(sheet.name(), "Sheet1");
```
```

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

### new_file_empty_worksheet

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Creates a new Workbook with default theme and stylesheet but no worksheets. At least one sheet must be added before writing the file.

```APIDOC
## new_file_empty_worksheet — Create a workbook without any sheets

Creates a new `Workbook` with default theme and stylesheet but **no** worksheets. At least one sheet must be added before writing the file.

```rust
use umya_spreadsheet::*

let mut book = new_file_empty_worksheet();
let _ = book.new_sheet("Report");
let _ = book.new_sheet("Summary");
```
```

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

### Code Formatting and Linting

Source: https://github.com/mathnya/umya-spreadsheet/blob/master/README.md

Commands to format code using `cargo fmt` and lint code using `clippy` with warnings disabled.

```bash
cargo +nightly fmt --all
cargo clippy -- -D warnings
```

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

### Create and Embed a Line Chart

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Creates a line chart and embeds it into a worksheet. Ensure data is populated before defining the chart series.

```rust
use umya_spreadsheet::*;
use umya_spreadsheet::structs::{Chart, ChartType};
use umya_spreadsheet::structs::drawing::spreadsheet::MarkerType;

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();

// Populate data
for i in 1..=10u32 {
    sheet.cell_mut((1, i)).set_value_number(i as f64);
    sheet.cell_mut((2, i)).set_value_number((i * i) as f64);
}

// Define chart placement
let mut from_marker = MarkerType::default();
from_marker.set_coordinate("C1");
let mut to_marker = MarkerType::default();
to_marker.set_coordinate("H15");

// Data series references
let series = vec!["Sheet1!$A$1:$A$10", "Sheet1!$B$1:$B$10"];

let mut chart = Chart::default();
chart.new_chart(ChartType::LineChart, from_marker, to_marker, series);

book.sheet_mut(0).unwrap().add_chart(chart);

let path = std::path::Path::new("./output_chart.xlsx");
umya_spreadsheet::writer::xlsx::write(&book, path).unwrap();
```

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

### Write a workbook to an XLSX file

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Serializes a Workbook to an XLSX file at the given path. Returns a Result indicating success or failure.

```rust
use umya_spreadsheet::*;
use umya_spreadsheet::writer;

let mut book = new_file();
book.sheet_mut(0).unwrap()
    .cell_mut("A1")
    .set_value("Hello, world!");

let path = std::path::Path::new("./output.xlsx");
writer::xlsx::write(&book, path).expect("Failed to write");
```

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

### Write Password-Protected XLSX Workbook

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Serializes and encrypts a workbook using AES-based OOXML encryption with a provided password. Ensure the password meets complexity requirements.

```rust
use umya_spreadsheet::*
use umya_spreadsheet::writer;

let mut book = new_file();
book.sheet_mut(0).unwrap()
    .cell_mut("A1")
    .set_value("Secret data");

let path = std::path::Path::new("./protected.xlsx");
writer::xlsx::write_with_password(&book, path, "MyP@ssw0rd")
    .expect("Failed to write protected file");
```

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

### Write XLSX File with Password

Source: https://github.com/mathnya/umya-spreadsheet/blob/master/README.md

Writes the workbook data to an XLSX file with password protection. The password must be a string.

```rust
let path = std::path::Path::new("./tests/result_files/bbb.xlsx");
let _unused =  umya_spreadsheet::writer::xlsx::write_with_password(&book, path, "password");
```

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

### Eagerly read an XLSX/XLSM file from a path

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Reads an XLSX/XLSM file, fully deserializing all worksheets into memory immediately. Returns a Result containing the Workbook or an XlsxError.

```rust
use umya_spreadsheet::reader;

let path = std::path::Path::new("./tests/test_files/aaa.xlsx");
match reader::xlsx::read(path) {
    Ok(book) => {
        let sheet = book.sheet(0).unwrap();
        let val = sheet.value("A1");
        println!("A1 = {val}");
    }
    Err(e) => eprintln!("Failed to read: {e}"),
}
```

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

### Copy Row and Column Styling

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Copies the styling from a source row or column to a destination row or column. Optional bounds can be specified to limit the copy operation to a subset of columns or rows.

```rust
use umya_spreadsheet::*
use umya_spreadsheet::reader;

let path = std::path::Path::new("./tests/test_files/aaa.xlsx");
let mut book = reader::xlsx::read(path).unwrap();
let sheet = book.sheet_mut(0).unwrap();

// Copy styling from row 3 to row 5 (all columns)
sheet.copy_row_styling(&3, &5, None, None);

// Copy styling from column 2 to column 6 (all rows)
sheet.copy_col_styling(&2, &6, None, None);
```

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

### Add New Chart to Sheet

Source: https://github.com/mathnya/umya-spreadsheet/blob/master/README.md

Creates and adds a new chart to a specified sheet. Requires defining chart type, markers, and data series.

```rust
let mut book = umya_spreadsheet::new_file();
// Add Chart
let mut from_marker = umya_spreadsheet::structs::drawing::spreadsheet::MarkerType::default();
from_marker.set_coordinate("C1");
let mut to_marker = umya_spreadsheet::structs::drawing::spreadsheet::MarkerType::default();
to_marker.set_coordinate("D11");
let area_chart_series_list = vec![
    "Sheet1!$A$1:$A$10",
    "Sheet1!$B$1:$B$10",
];
let mut chart = umya_spreadsheet::structs::Chart::default();
chart.new_chart(
    umya_spreadsheet::structs::ChartType::LineChart,
    from_marker,
    to_marker,
    area_chart_series_list,
);
book.get_sheet_by_name_mut("Sheet1").unwrap()
    .add_chart(chart);
```

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

### Embed an Image into a Worksheet

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Loads an image from disk and anchors it to a specific cell. Ensure the image file exists at the specified path.

```rust
use umya_spreadsheet::*;
use umya_spreadsheet::structs::Image;
use umya_spreadsheet::structs::drawing::spreadsheet::MarkerType;

let mut book = new_file();

let mut marker = MarkerType::default();
marker.set_coordinate("B3");

let mut image = Image::default();
image.new_image("./images/sample1.png", marker);

book.sheet_by_name_mut("Sheet1").unwrap().add_image(image);

let path = std::path::Path::new("./output_image.xlsx");
umya_spreadsheet::writer::xlsx::write(&book, path).unwrap();
```

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

### writer::xlsx::write_with_password

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Serializes and encrypts a workbook using the supplied password with AES-based OOXML encryption.

```APIDOC
## `writer::xlsx::write_with_password` — Write password-protected workbook

Serialises and encrypts a workbook using the supplied password (AES-based OOXML encryption).

### Usage

```rust
use umya_spreadsheet::*;
use umya_spreadsheet::writer;

let mut book = new_file();
book.sheet_mut(0).unwrap()
    .cell_mut("A1")
    .set_value("Secret data");

let path = std::path::Path::new("./protected.xlsx");
writer::xlsx::write_with_password(&book, path, "MyP@ssw0rd")
    .expect("Failed to write protected file");
```
```

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

### Copy Row and Column Styling

Source: https://github.com/mathnya/umya-spreadsheet/blob/master/README.md

Copies the style of a specified row or column to another. Use `None` for default parameters.

```rust
let mut book = umya_spreadsheet::reader::xlsx::read(path).unwrap();
let sheet = book.get_sheet_mut(&0).unwrap();
sheet.copy_row_styling(&3, &5, None, None);
sheet.copy_col_styling(&3, &5, None, None);
```

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

### Add New Worksheet to Workbook

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Appends a new, empty worksheet with a specified name to the workbook. Returns a mutable reference to the new worksheet.

```rust
use umya_spreadsheet::*

let mut book = new_file();
let sheet2 = book.new_sheet("Q1 Data").unwrap();
sheet2.cell_mut("A1").set_value("Quarter");

let sheet3 = book.new_sheet("Q2 Data").unwrap();
sheet3.cell_mut("A1").set_value("Quarter");

println!("Sheet count: {}", book.sheet_count());
```

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

### Add Password to Existing XLSX File

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Reads an existing XLSX file and writes a password-encrypted copy to a new path. The original file remains unmodified.

```rust
use umya_spreadsheet::writer;

let from = std::path::Path::new("./original.xlsx");
let to   = std::path::Path::new("./protected.xlsx");
writer::xlsx::set_password(from, to, "secret123")
    .expect("Failed to encrypt file");
```

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

### Write XLSX File

Source: https://github.com/mathnya/umya-spreadsheet/blob/master/README.md

Writes the current workbook data to an XLSX file at the specified path. The return value is ignored using `_unused`.

```rust
let path = std::path::Path::new("./tests/result_files/bbb.xlsx");
let _unused =  umya_spreadsheet::writer::xlsx::write(&book, path);
```

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

### Workbook::add_sheet

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Clones an existing worksheet and adds it to the workbook with a new specified name.

```APIDOC
## `Workbook::add_sheet` (clone worksheet) — Copy a worksheet

Clones an existing worksheet and adds it to the workbook under a new name.

```rust
use umya_spreadsheet::*;

let mut book = new_file();
book.sheet_mut(0).unwrap()
    .cell_mut("A1")
    .set_value("Template data");

// Clone "Sheet1" → "Sheet1 Copy"
let mut clone = book.sheet(0).unwrap().clone();
clone.set_name("Sheet1 Copy");
book.add_sheet(clone).unwrap();

println!("Sheets: {}", book.sheet_count()); // 2
assert_eq!(book.sheet(1).unwrap().value("A1"), "Template data");
```
```

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

### Workbook::sheet_by_name / Workbook::sheet_by_name_mut

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Retrieves a worksheet by its exact name string. Returns `Option<&Worksheet>` or `Option<&mut Worksheet>`.

```APIDOC
## `Workbook::sheet_by_name` / `Workbook::sheet_by_name_mut` — Access worksheets by name

Retrieves a worksheet by its exact name string. Returns `Option<&Worksheet>` / `Option<&mut Worksheet>`.

### Usage

```rust
use umya_spreadsheet::*;

let mut book = new_file();
book.sheet_by_name_mut("Sheet1")
    .unwrap()
    .cell_mut("D4")
    .set_value("Hello");

let val = book.sheet_by_name("Sheet1")
    .unwrap()
    .value("D4");
assert_eq!(val, "Hello");
```
```

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

### Export Worksheet as CSV

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Writes a single worksheet from a workbook to a CSV file. Options for CSV formatting can be provided.

```rust
use umya_spreadsheet::*
use umya_spreadsheet::writer;

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();
sheet.cell_mut("A1").set_value("Name");
sheet.cell_mut("B1").set_value("Score");
sheet.cell_mut("A2").set_value("Alice");
sheet.cell_mut("B2").set_value_number(95.5_f64);

let path = std::path::Path::new("./output.csv");
let option = structs::CsvWriterOption::default();
writer::csv::write(&book, path, Some(&option))
    .expect("Failed to write CSV");
```

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

### Set Password for Existing XLSX File

Source: https://github.com/mathnya/umya-spreadsheet/blob/master/README.md

Applies password protection to an existing XLSX file, saving the result to a new path. This operation does not modify the original file.

```rust
let from_path = std::path::Path::new("./tests/test_files/aaa.xlsx");
let to_path = std::path::Path::new("./tests/result_files/bbb.xlsx");
let _unused =  umya_spreadsheet::writer::xlsx::set_password(&from_path, &to_path, "password");
```

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

### Chart::new_chart

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Creates a chart of the specified type and embeds it into the spreadsheet, anchored to a rectangular area defined by two corner coordinates.

```APIDOC
## `Chart::new_chart` — Create and embed a chart

Creates a chart of the specified type anchored to a rectangular area defined by two `MarkerType` corner coordinates.

```rust
use umya_spreadsheet::*;
use umya_spreadsheet::structs::{Chart, ChartType};
use umya_spreadsheet::structs::drawing::spreadsheet::MarkerType;

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();

// Populate data
for i in 1..=10u32 {
    sheet.cell_mut((1, i)).set_value_number(i as f64);
    sheet.cell_mut((2, i)).set_value_number((i * i) as f64);
}

// Define chart placement
let mut from_marker = MarkerType::default();
from_marker.set_coordinate("C1");
let mut to_marker = MarkerType::default();
to_marker.set_coordinate("H15");

// Data series references
let series = vec!["Sheet1!$A$1:$A$10", "Sheet1!$B$1:$B$10"];

let mut chart = Chart::default();
chart.new_chart(ChartType::LineChart, from_marker, to_marker, series);

book.sheet_mut(0).unwrap().add_chart(chart);

let path = std::path::Path::new("./output_chart.xlsx");
umya_spreadsheet::writer::xlsx::write(&book, path).unwrap();
```
```

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

### Read XLSX File

Source: https://github.com/mathnya/umya-spreadsheet/blob/master/README.md

Reads an XLSX file from the specified path. Ensure the path points to a valid .xlsx file.

```rust
let path = std::path::Path::new("./tests/test_files/aaa.xlsx");
let mut book = umya_spreadsheet::reader::xlsx::read(path).unwrap();
```

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

### Copy a Worksheet

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Clones an existing worksheet and adds it to the workbook with a new name. This is useful for duplicating sheet structures and content.

```rust
use umya_spreadsheet::*;

let mut book = new_file();
book.sheet_mut(0).unwrap()
    .cell_mut("A1")
    .set_value("Template data");

// Clone "Sheet1" → "Sheet1 Copy"
let mut clone = book.sheet(0).unwrap().clone();
clone.set_name("Sheet1 Copy");
book.add_sheet(clone).unwrap();

println!("Sheets: {}", book.sheet_count()); // 2
assert_eq!(book.sheet(1).unwrap().value("A1"), "Template data");
```

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

### Access Worksheets by Index

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Retrieves worksheets using their zero-based index. `sheet` provides immutable access, while `sheet_mut` provides mutable access.

```rust
use umya_spreadsheet::*

let mut book = new_file();
let _ = book.new_sheet("Sheet2");

// Immutable access
let name = book.sheet(0).unwrap().name().to_string();
println!("First sheet: {name}");

// Mutable access
book.sheet_mut(1).unwrap()
    .cell_mut("C3")
    .set_value("edited");
```

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

### Workbook::new_sheet

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Appends a new, empty worksheet with the given name to the workbook.

```APIDOC
## `Workbook::new_sheet` — Add a worksheet

Appends a new, empty worksheet with the given name to the workbook. Returns `Result<&mut Worksheet, XlsxError>`.

### Usage

```rust
use umya_spreadsheet::*;

let mut book = new_file();
let sheet2 = book.new_sheet("Q1 Data").unwrap();
sheet2.cell_mut("A1").set_value("Quarter");

let sheet3 = book.new_sheet("Q2 Data").unwrap();
sheet3.cell_mut("A1").set_value("Quarter");

println!("Sheet count: {}", book.sheet_count());
```
```

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

### Lazily read an XLSX/XLSM file from a path

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Reads the workbook structure but delays deserializing each worksheet until it is first accessed. This reduces memory usage and startup time for large files.

```rust
use umya_spreadsheet::reader;

let path = std::path::Path::new("./tests/test_files/aaa.xlsx");
let mut book = reader::xlsx::lazy_read(path).unwrap();

// Worksheet data is loaded on first access
let val = book.sheet(0).unwrap().value("B2");
println!("B2 = {val}");
```

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

### Set Cell Formulas with Cached Results

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Apply Excel formulas to cells using `set_formula`. Optionally, provide a pre-computed cached result with `set_formula_result_number` for compatibility with readers that do not recalculate formulas.

```rust
use umya_spreadsheet::*

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();

sheet.cell_mut("A1").set_value_number(10_i32);
sheet.cell_mut("A2").set_value_number(20_i32);

// Set formula with a cached numeric result
sheet.cell_mut("A3")
    .set_formula("SUM(A1:A2)")
    .set_formula_result_number(30.0_f64);

assert!(sheet.cell("A3").unwrap().is_formula());
assert_eq!(sheet.cell("A3").unwrap().formula(), "SUM(A1:A2)");
assert_eq!(sheet.value("A3"), "30");
```

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

### Access Worksheets by Name

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Retrieves worksheets by their exact name string. Provides both immutable (`sheet_by_name`) and mutable (`sheet_by_name_mut`) access.

```rust
use umya_spreadsheet::*

let mut book = new_file();
book.sheet_by_name_mut("Sheet1")
    .unwrap()
    .cell_mut("D4")
    .set_value("Hello");

let val = book.sheet_by_name("Sheet1")
    .unwrap()
    .value("D4");
assert_eq!(val, "Hello");
```

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

### Worksheet::copy_row_styling / copy_col_styling

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Copies the styling from a source row or column to a destination row or column.

```APIDOC
## Worksheet::copy_row_styling / copy_col_styling

### Description
Copies the style of a source row (or column) to a destination row (or column), with optional start/end column (or row) bounds.

### Method
```rust
// Copy styling from row 3 to row 5 (all columns)
sheet.copy_row_styling(&3, &5, None, None);

// Copy styling from column 2 to column 6 (all rows)
sheet.copy_col_styling(&2, &6, None, None);
```

### Parameters
- **source_index** (integer) - The index of the source row or column.
- **destination_index** (integer) - The index of the destination row or column.
- **start_bound** (optional integer) - The starting bound for columns (for rows) or rows (for columns).
- **end_bound** (optional integer) - The ending bound for columns (for rows) or rows (for columns).
```

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

### Apply Style to Cell Range

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Applies a single Style instance to all cells within a specified range. Ensure the Style object is properly configured before applying.

```rust
use umya_spreadsheet::*

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();

let mut style = Style::default();
style.get_borders_mut()
     .get_bottom_mut()
     .set_border_style(Border::BORDER_MEDIUM);
style.set_background_color(Color::COLOR_YELLOW_STR);

sheet.set_style_by_range("A1:C5", &style);
```

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

### Image::new_image / Worksheet::add_image

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Loads an image file from disk and embeds it into the worksheet, anchoring it at a specified cell coordinate.

```APIDOC
## `Image::new_image` / `Worksheet::add_image` — Embed an image

Loads an image file from disk and anchors it in the worksheet at the specified cell coordinate.

```rust
use umya_spreadsheet::*;
use umya_spreadsheet::structs::Image;
use umya_spreadsheet::structs::drawing::spreadsheet::MarkerType;

let mut book = new_file();

let mut marker = MarkerType::default();
marker.set_coordinate("B3");

let mut image = Image::default();
image.new_image("./images/sample1.png", marker);

book.sheet_by_name_mut("Sheet1").unwrap().add_image(image);

let path = std::path::Path::new("./output_image.xlsx");
umya_spreadsheet::writer::xlsx::write(&book, path).unwrap();
```
```

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

### Enable Auto-Filter on a Column Range

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Sets up an auto-filter for a specified range of cells, typically the header row, to enable filtering in Excel.

```rust
use umya_spreadsheet::*;

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();

sheet.cell_mut("A1").set_value("Name");
sheet.cell_mut("B1").set_value("Score");
sheet.cell_mut("A2").set_value("Alice");
sheet.cell_mut("B2").set_value_number(90_i32);
sheet.cell_mut("A3").set_value("Bob");
sheet.cell_mut("B3").set_value_number(75_i32);

sheet.set_auto_filter("A1:B1");
```

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

### writer::xlsx::set_password

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Adds a password to an existing XLSX file by reading it and writing a password-encrypted copy to a new path.

```APIDOC
## `writer::xlsx::set_password` — Add password to an existing file

Reads an existing XLSX file and writes a password-encrypted copy to a new path without modifying the original.

### Usage

```rust
use umya_spreadsheet::writer;

let from = std::path::Path::new("./original.xlsx");
let to   = std::path::Path::new("./protected.xlsx");
writer::xlsx::set_password(from, to, "secret123")
    .expect("Failed to encrypt file");
```
```

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

### Image::download_image

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Exports an embedded image from a worksheet and saves it to a specified file path on disk.

```APIDOC
## `Image::download_image` — Export an embedded image to disk

Extracts an embedded image from a worksheet and saves it to the given file path.

```rust
use umya_spreadsheet::reader;

let path = std::path::Path::new("./tests/test_files/aaa.xlsx");
let book = reader::xlsx::read(path).unwrap();
let sheet = book.sheet_by_name("Sheet1").unwrap();

if let Some(image) = sheet.image_collection().first() {
    image.download_image("./extracted_image.png");
    println!("Image saved.");
}
```
```

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

### writer::xlsx::write

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Serializes a Workbook to an XLSX file at the specified path. Returns `Result<(), XlsxError>`.

```APIDOC
## writer::xlsx::write — Write workbook to a file

Serialises a `Workbook` to an XLSX file at the given path. Returns `Result<(), XlsxError>`.

```rust
use umya_spreadsheet::*
use umya_spreadsheet::writer;

let mut book = new_file();
book.sheet_mut(0).unwrap()
    .cell_mut("A1")
    .set_value("Hello, world!");

let path = std::path::Path::new("./output.xlsx");
writer::xlsx::write(&book, path).expect("Failed to write");
```
```

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

### Read XLSX/XLSM from any Read + Seek source

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Reads an XLSX/XLSM file from any `io::Read + io::Seek` source, such as an in-memory buffer or network stream. The `with_sheet_read` flag controls eager vs. lazy sheet loading.

```rust
use std::fs::File;
use umya_spreadsheet::reader::xlsx::read_reader;

let file = File::open("./tests/test_files/aaa.xlsx").unwrap();
let book = read_reader(file, true).unwrap(); // true = eager load

// Works equally with a Cursor<Vec<u8>> for in-memory bytes
let bytes = std::fs::read("./tests/test_files/aaa.xlsx").unwrap();
let cursor = std::io::Cursor::new(bytes);
let book2 = read_reader(cursor, false).unwrap(); // false = lazy load
```

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

### Set Rich Text Content in Cells

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Use `set_rich_text` to assign formatted `RichText` objects to cells, enabling multiple font styles (like bold) within a single cell.

```rust
use umya_spreadsheet::*

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();

let mut run1 = structs::TextElement::default();
run1.set_text("Bold ");
run1.get_run_properties_mut().set_bold(true);

let mut run2 = structs::TextElement::default();
run2.set_text("Normal");

let mut rich = structs::RichText::default();
rich.add_rich_text_elements(run1);
rich.add_rich_text_elements(run2);

sheet.cell_mut("A1").set_rich_text(rich);
```

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

### Read Formatted Cell Values

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Retrieve a cell's value as a formatted string, respecting its number format (e.g., currency, percentage, date). Requires reading an existing XLSX file.

```rust
use umya_spreadsheet::*

let path = std::path::Path::new("./tests/test_files/aaa.xlsx");
let book = umya_spreadsheet::reader::xlsx::read(path).unwrap();
let sheet = book.sheet(0).unwrap();

// Returns the value formatted according to the cell's number format
let formatted = sheet.formatted_value("C5");
println!("Formatted: {formatted}");
```

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

### Add Cell Comments

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Creates and attaches an annotation comment to a specific cell within a worksheet. Use `Comment::new_comment` to initialize and `set_text_string` to add the comment's content.

```rust
use umya_spreadsheet::*
use umya_spreadsheet::reader;

let path = std::path::Path::new("./tests/test_files/aaa.xlsx");
let mut book = reader::xlsx::read(path).unwrap();
let sheet = book.sheet_mut(0).unwrap();

let mut comment = structs::Comment::default();
comment.new_comment("B2");
comment.set_text_string("This value needs review");
sheet.add_comments(comment);

assert!(sheet.has_comments());
```

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

### Export an Embedded Image to Disk

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Extracts an image embedded in a worksheet and saves it to a specified file path. This requires reading an existing Excel file.

```rust
use umya_spreadsheet::reader;

let path = std::path::Path::new("./tests/test_files/aaa.xlsx");
let book = reader::xlsx::read(path).unwrap();
let sheet = book.sheet_by_name("Sheet1").unwrap();

if let Some(image) = sheet.image_collection().first() {
    image.download_image("./extracted_image.png");
    println!("Image saved.");
}
```

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

### Workbook::sheet / Workbook::sheet_mut

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Retrieves a worksheet by its zero-based index. `sheet` returns an immutable reference, while `sheet_mut` returns a mutable one.

```APIDOC
## `Workbook::sheet` / `Workbook::sheet_mut` — Access worksheets by index

Retrieves a worksheet by zero-based index. `sheet` returns an immutable reference; `sheet_mut` returns a mutable one. Returns `Option<&Worksheet>` / `Option<&mut Worksheet>`.

### Usage

```rust
use umya_spreadsheet::*;

let mut book = new_file();
let _ = book.new_sheet("Sheet2");

// Immutable access
let name = book.sheet(0).unwrap().name().to_string();
println!("First sheet: {name}");

// Mutable access
book.sheet_mut(1).unwrap()
    .cell_mut("C3")
    .set_value("edited");
```
```

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

### Merge Cells in a Range

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Registers a range of cells to be merged. Only the value and style of the top-left cell will be displayed; other cells in the range become visually blank. Use `merge_cells()` to check existing merged ranges.

```rust
use umya_spreadsheet::*

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();

sheet.cell_mut("A1").set_value("Merged header");
sheet.add_merge_cells("A1:D1");

// Check merged ranges
let ranges = sheet.merge_cells();
println!("Merged ranges: {}", ranges.len()); // 1
```

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

### Mutably Access and Modify Cell Styles

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Obtain a mutable reference to a cell's `Style` using `style_mut`. This allows modification of properties like background color, font attributes (bold, color), and borders. The cell entry is created if it doesn't exist.

```rust
use umya_spreadsheet::*

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();

// Set background fill color
sheet.style_mut("A1")
    .set_background_color(Color::COLOR_RED_STR);

// Set font color and bold
let style = sheet.style_mut("B1");
style.get_font_mut().set_bold(true);
style.get_font_mut().get_color_mut().set_argb(Color::COLOR_RED);

// Set borders
let style = sheet.style_mut("C1");
style.get_borders_mut().get_bottom_mut().set_border_style(Border::BORDER_MEDIUM);
style.get_borders_mut().get_top_mut().set_border_style(Border::BORDER_MEDIUM);
style.get_borders_mut().get_left_mut().set_border_style(Border::BORDER_THIN);
style.get_borders_mut().get_right_mut().set_border_style(Border::BORDER_THIN);
```

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

### writer::csv::write

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Exports a single worksheet as a CSV file using configurable `CsvWriterOption`.

```APIDOC
## `writer::csv::write` — Export a single worksheet as CSV

Writes a single worksheet from a workbook to a CSV file using a configurable `CsvWriterOption`.

### Usage

```rust
use umya_spreadsheet::*;
use umya_spreadsheet::writer;

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();
sheet.cell_mut("A1").set_value("Name");
sheet.cell_mut("B1").set_value("Score");
sheet.cell_mut("A2").set_value("Alice");
sheet.cell_mut("B2").set_value_number(95.5_f64);

let path = std::path::Path::new("./output.csv");
let option = structs::CsvWriterOption::default();
writer::csv::write(&book, path, Some(&option))
    .expect("Failed to write CSV");
```
```

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

### Set Cell Value with Auto Type Detection

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

The `set_value` method automatically parses string input into the most appropriate internal type: empty, numeric, boolean, error, or string.

```rust
use umya_spreadsheet::*

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();

sheet.cell_mut("A1").set_value("Hello");        // → String
sheet.cell_mut("A2").set_value("3.14");          // → Numeric(3.14)
sheet.cell_mut("A3").set_value("TRUE");          // → Bool(true)
sheet.cell_mut("A4").set_value("#DIV/0!");        // → Error
sheet.cell_mut("A5").set_value("");              // → Empty
```

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

### Read XLSX File Lazily

Source: https://github.com/mathnya/umya-spreadsheet/blob/master/README.md

Reads an XLSX file lazily, delaying worksheet loading until accessed. This can improve response times for large files.

```rust
let path = std::path::Path::new("./tests/test_files/aaa.xlsx");
let mut book = umya_spreadsheet::reader::lazy_read(path).unwrap();
```

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

### Workbook::insert_new_column / Workbook::remove_column

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Inserts or removes columns by letter name or numeric index, automatically adjusting all coordinates and formula references.

```APIDOC
## `Workbook::insert_new_column` / `Workbook::remove_column` — Insert and remove columns

Inserts or removes columns by letter name or numeric index, adjusting all coordinates and formula references automatically.

### Usage

```rust
use umya_spreadsheet::*;

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();
sheet.cell_mut("A1").set_value("Col A");
sheet.cell_mut("B1").set_value("Col B");

// Insert 1 blank column before column B
book.insert_new_column("Sheet1", "B", 1);
// "Col B" is now in C1

// Or use the index variant (column B = index 2)
book.insert_new_column_by_index("Sheet1", 2, 1);

// Remove 2 columns starting at column F
book.remove_column("Sheet1", "F", 2);
book.remove_column_by_index("Sheet1", 6, 2);
```
```

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

### reader::xlsx::read

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Eagerly reads an XLSX/XLSM file from a file path, fully deserializing all worksheets into memory immediately. Returns `Result<Workbook, XlsxError>`.

```APIDOC
## reader::xlsx::read — Eager read from a file path

Reads an XLSX/XLSM file, fully deserialising all worksheets into memory immediately. Returns `Result<Workbook, XlsxError>`.

```rust
use umya_spreadsheet::reader;

let path = std::path::Path::new("./tests/test_files/aaa.xlsx");
match reader::xlsx::read(path) {
    Ok(book) => {
        let sheet = book.sheet(0).unwrap();
        let val = sheet.value("A1");
        println!("A1 = {val}");
    }
    Err(e) => eprintln!("Failed to read: {e}"),
}
```
```

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

### Worksheet::set_style_by_range

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Applies a specified Style instance to all cells within a given range.

```APIDOC
## Worksheet::set_style_by_range

### Description
Applies the same `Style` instance to every cell in the specified range (e.g. `"A1:D10"`).

### Method
```rust
sheet.set_style_by_range("A1:C5", &style);
```

### Parameters
- **range** (string) - The range of cells to apply the style to (e.g., `"A1:C5"`).
- **style** (*Style) - A reference to the `Style` object to apply.
```

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

### Add New Comment to Cell

Source: https://github.com/mathnya/umya-spreadsheet/blob/master/README.md

Creates and adds a new comment to a specified cell in the worksheet. The comment text can be set using `set_text_string`.

```rust
let mut book = umya_spreadsheet::reader::xlsx::read(path).unwrap();
let sheet = book.get_sheet_mut(&0).unwrap();
let mut comment = Comment::default();
comment.new_comment("B2");
comment.set_text_string("TEST");
sheet.add_comments(comment);
```

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

### Add Conditional Formatting Rule

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Applies a conditional formatting rule to a range of cells, such as highlighting cells greater than a certain value. Requires specifying the range, rule type, operator, and formatting style.

```rust
use umya_spreadsheet::*;

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();
for i in 1..=5u32 {
    sheet.cell_mut((1, i)).set_value_number(i as f64 * 10.0);
}

let mut cf = structs::ConditionalFormatting::default();
cf.add_sqref("A1:A5");

let mut rule = structs::ConditionalFormattingRule::default();
rule.set_type(structs::ConditionalFormatValues::CellIs);
rule.set_operator(structs::ConditionalFormattingOperatorValues::GreaterThan);
rule.set_formula_1("30");

let mut style = structs::DifferentialFormat::default();
style.get_fill_mut().get_pattern_fill_mut().set_background_color(Color::COLOR_RED_STR);
rule.set_differential_format(style);

cf.add_conditional_formatting_rule(rule);
sheet.add_conditional_formatting_collection(cf);
```

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

### Cell::set_value

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Sets a cell's value by automatically detecting the most appropriate data type (empty, numeric, boolean, error, or string) from the input string.

```APIDOC
## `Cell::set_value` — Set a cell value with auto type detection

Parses the string input and converts it to the most appropriate internal type: empty, numeric, boolean, error, or string.

```rust
use umya_spreadsheet::*

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();

sheet.cell_mut("A1").set_value("Hello");        // → String
sheet.cell_mut("A2").set_value("3.14");          // → Numeric(3.14)
sheet.cell_mut("A3").set_value("TRUE");          // → Bool(true)
sheet.cell_mut("A4").set_value("#DIV/0!");        // → Error
sheet.cell_mut("A5").set_value("");              // → Empty
```
```

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

### Retrieve Cell Values by Range

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Returns a vector of `CellValue` references for all cells within a specified range. The values are sorted by row, then by column. Useful for calculations or data aggregation.

```rust
use umya_spreadsheet::*

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();
sheet.cell_mut("A1").set_value_number(1_i32);
sheet.cell_mut("B1").set_value_number(2_i32);
sheet.cell_mut("A2").set_value_number(3_i32);
sheet.cell_mut("B2").set_value_number(4_i32);

let values = book.sheet(0).unwrap().cell_value_by_range("A1:B2");
let sum: f64 = values.iter()
    .filter_map(|cv| cv.value_number())
    .sum();
println!("Sum = {sum}"); // 10
```

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

### Worksheet::style_mut

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Provides mutable access to a cell's style object, allowing modification of properties such as background color, font, and borders. Creates the cell entry if it doesn't exist.

```APIDOC
## `Worksheet::style_mut` — Mutably access a cell's style

Returns a `&mut Style` for the cell at the given coordinate, creating the cell entry if it does not yet exist.

```rust
use umya_spreadsheet::*

let mut book = new_file();
let sheet = book.sheet_mut(0).unwrap();

// Set background fill color
sheet.style_mut("A1")
    .set_background_color(Color::COLOR_RED_STR);

// Set font color and bold
let style = sheet.style_mut("B1");
style.get_font_mut().set_bold(true);
style.get_font_mut().get_color_mut().set_argb(Color::COLOR_RED);

// Set borders
let style = sheet.style_mut("C1");
style.get_borders_mut().get_bottom_mut().set_border_style(Border::BORDER_MEDIUM);
style.get_borders_mut().get_top_mut().set_border_style(Border::BORDER_MEDIUM);
style.get_borders_mut().get_left_mut().set_border_style(Border::BORDER_THIN);
style.get_borders_mut().get_right_mut().set_border_style(Border::BORDER_THIN);
```
```

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

### Workbook::cell_value_by_address

Source: https://context7.com/mathnya/umya-spreadsheet/llms.txt

Retrieves cell values using a sheet-qualified address string.

```APIDOC
## Workbook::cell_value_by_address

### Description
Gets a list of `CellValue` references using an address string in the form `"SheetName!A1:C5"`.

### Method
```rust
let values = book.cell_value_by_address("Sheet1!A1:A2");
```

### Parameters
- **address** (string) - The sheet-qualified address string (e.g., `"Sheet1!A1:A2"`).

### Returns
- **Vec<&CellValue>** - A vector of references to `CellValue` objects matching the address.
```