Struct Workbook 

pub struct Workbook { /* private fields */ }

In-memory representation of an .xlsx workbook.

Implementations

impl Workbook

pub fn get_cell_value(&self, sheet: &str, cell: &str) -> Result<CellValue>

Get the value of a cell.

Returns CellValue::Empty for cells that have no value or do not exist in the sheet data.

pub fn set_cell_value( &mut self, sheet: &str, cell: &str, value: impl Into<CellValue>, ) -> Result<()>

Set the value of a cell.

The value can be any type that implements Into<CellValue>, including &str, String, f64, i32, i64, and bool.

Setting a cell to CellValue::Empty removes the cell from the row.

pub fn add_style(&mut self, style: &Style) -> Result<u32>

Register a new style and return its ID.

The style is deduplicated: if an identical style already exists in the stylesheet, the existing ID is returned.

pub fn get_cell_style(&self, sheet: &str, cell: &str) -> Result<Option<u32>>

Get the style ID applied to a cell.

Returns None if the cell does not exist or has no explicit style (i.e. uses the default style 0).

pub fn set_cell_style( &mut self, sheet: &str, cell: &str, style_id: u32, ) -> Result<()>

Set the style ID for a cell.

If the cell does not exist, an empty cell with just the style is created. The style_id must be a valid index in cellXfs.

pub fn merge_cells( &mut self, sheet: &str, top_left: &str, bottom_right: &str, ) -> Result<()>

Merge a range of cells on the given sheet.

top_left and bottom_right are cell references like “A1” and “C3”. Returns an error if the range overlaps with an existing merge region.

pub fn unmerge_cell(&mut self, sheet: &str, reference: &str) -> Result<()>

Remove a merged cell range from the given sheet.

reference is the exact range string like “A1:C3”.

pub fn get_merge_cells(&self, sheet: &str) -> Result<Vec<String>>

Get all merged cell ranges on the given sheet.

Returns a list of range strings like ["A1:B2", "D1:F3"].

pub fn set_cell_formula( &mut self, sheet: &str, cell: &str, formula: &str, ) -> Result<()>

Set a formula on a cell.

This is a convenience wrapper around [set_cell_value] with CellValue::Formula.

pub fn fill_formula( &mut self, sheet: &str, range: &str, formula: &str, ) -> Result<()>

Fill a range of cells with a formula, adjusting row references for each row relative to the first cell in the range.

range is an A1-style range like "D2:D10". The formula is the base formula for the first cell of the range. For each subsequent row, the row references in the formula are shifted by the row offset. Absolute row references ($1) are left unchanged.

pub fn set_cell_rich_text( &mut self, sheet: &str, cell: &str, runs: Vec<RichTextRun>, ) -> Result<()>

Set a cell to a rich text value (multiple formatted runs).

pub fn get_cell_rich_text( &self, sheet: &str, cell: &str, ) -> Result<Option<Vec<RichTextRun>>>

Get rich text runs for a cell, if it contains rich text.

Returns None if the cell is empty, contains a plain string, or holds a non-string value.

impl Workbook

pub fn add_pivot_table(&mut self, config: &PivotTableConfig) -> Result<()>

Add a pivot table to the workbook.

The pivot table summarizes data from config.source_sheet / config.source_range and places its output on config.target_sheet starting at config.target_cell.

pub fn get_pivot_tables(&self) -> Vec<PivotTableInfo>

Get information about all pivot tables in the workbook.

pub fn delete_pivot_table(&mut self, name: &str) -> Result<()>

Delete a pivot table by name.

pub fn add_sparkline( &mut self, sheet: &str, config: &SparklineConfig, ) -> Result<()>

Add a sparkline to a worksheet.

pub fn get_sparklines(&self, sheet: &str) -> Result<Vec<SparklineConfig>>

Get all sparklines for a worksheet.

pub fn remove_sparkline(&mut self, sheet: &str, location: &str) -> Result<()>

Remove a sparkline by its location cell reference.

pub fn evaluate_formula(&self, sheet: &str, formula: &str) -> Result<CellValue>

Evaluate a single formula string in the context of sheet.

A [CellSnapshot] is built from the current workbook state so that cell references within the formula can be resolved.

pub fn calculate_all(&mut self) -> Result<()>

Recalculate every formula cell across all sheets and store the computed result back into each cell. Uses a dependency graph and topological sort so formulas are evaluated after their dependencies.

pub fn get_occupied_cells(&self, sheet: &str) -> Result<Vec<(u32, u32)>>

Return (col, row) pairs for all occupied cells on the named sheet.

pub fn set_doc_props(&mut self, props: DocProperties)

Set the core document properties (title, author, etc.).

pub fn get_doc_props(&self) -> DocProperties

Get the core document properties.

pub fn set_app_props(&mut self, props: AppProperties)

Set the application properties (company, app version, etc.).

pub fn get_app_props(&self) -> AppProperties

Get the application properties.

pub fn set_custom_property(&mut self, name: &str, value: CustomPropertyValue)

Set a custom property by name. If a property with the same name already exists, its value is replaced.

pub fn get_custom_property(&self, name: &str) -> Option<CustomPropertyValue>

Get a custom property value by name, or None if it does not exist.

pub fn delete_custom_property(&mut self, name: &str) -> bool

Remove a custom property by name. Returns true if a property was found and removed.

impl Workbook

pub fn add_chart( &mut self, sheet: &str, from_cell: &str, to_cell: &str, config: &ChartConfig, ) -> Result<()>

Add a chart to a sheet, anchored between two cells.

The chart spans from from_cell (e.g., "B2") to to_cell (e.g., "J15"). The config specifies the chart type, series data, title, and legend visibility.

pub fn add_image(&mut self, sheet: &str, config: &ImageConfig) -> Result<()>

Add an image to a sheet from bytes.

The image is anchored to the cell specified in config.from_cell. Dimensions are specified in pixels via config.width_px and config.height_px.

impl Workbook

pub fn add_data_validation( &mut self, sheet: &str, config: &DataValidationConfig, ) -> Result<()>

Add a data validation rule to a sheet.

pub fn get_data_validations( &self, sheet: &str, ) -> Result<Vec<DataValidationConfig>>

Get all data validation rules for a sheet.

pub fn remove_data_validation(&mut self, sheet: &str, sqref: &str) -> Result<()>

Remove a data validation rule matching the given cell range from a sheet.

pub fn set_conditional_format( &mut self, sheet: &str, sqref: &str, rules: &[ConditionalFormatRule], ) -> Result<()>

Set conditional formatting rules on a cell range of a sheet.

pub fn get_conditional_formats( &self, sheet: &str, ) -> Result<Vec<(String, Vec<ConditionalFormatRule>)>>

Get all conditional formatting rules for a sheet.

Returns a list of (sqref, rules) pairs.

pub fn delete_conditional_format( &mut self, sheet: &str, sqref: &str, ) -> Result<()>

Delete conditional formatting rules for a specific cell range on a sheet.

pub fn add_comment(&mut self, sheet: &str, config: &CommentConfig) -> Result<()>

Add a comment to a cell on the given sheet.

A VML drawing part is generated automatically when saving so that the comment renders correctly in Excel.

pub fn get_comments(&self, sheet: &str) -> Result<Vec<CommentConfig>>

Get all comments for a sheet.

pub fn remove_comment(&mut self, sheet: &str, cell: &str) -> Result<()>

Remove a comment from a cell on the given sheet.

When the last comment on a sheet is removed, the VML drawing part is cleaned up automatically during save.

pub fn set_auto_filter(&mut self, sheet: &str, range: &str) -> Result<()>

Set an auto-filter on a sheet for the given cell range.

pub fn remove_auto_filter(&mut self, sheet: &str) -> Result<()>

Remove the auto-filter from a sheet.

pub fn set_panes(&mut self, sheet: &str, cell: &str) -> Result<()>

Set freeze panes on a sheet.

The cell reference indicates the top-left cell of the scrollable area. For example, "A2" freezes row 1, "B1" freezes column A, and "B2" freezes both row 1 and column A.

pub fn unset_panes(&mut self, sheet: &str) -> Result<()>

Remove any freeze or split panes from a sheet.

pub fn get_panes(&self, sheet: &str) -> Result<Option<String>>

Get the current freeze pane cell reference for a sheet, if any.

Returns the top-left cell of the unfrozen area (e.g., "A2" if row 1 is frozen), or None if no panes are configured.

pub fn set_page_margins( &mut self, sheet: &str, margins: &PageMarginsConfig, ) -> Result<()>

Set page margins on a sheet.

pub fn get_page_margins(&self, sheet: &str) -> Result<PageMarginsConfig>

Get page margins for a sheet, returning Excel defaults if not set.

pub fn set_page_setup( &mut self, sheet: &str, orientation: Option<Orientation>, paper_size: Option<PaperSize>, scale: Option<u32>, fit_to_width: Option<u32>, fit_to_height: Option<u32>, ) -> Result<()>

Set page setup options (orientation, paper size, scale, fit-to-page).

Only non-None parameters are applied; existing values for None parameters are preserved.

pub fn get_orientation(&self, sheet: &str) -> Result<Option<Orientation>>

Get the page orientation for a sheet.

pub fn get_paper_size(&self, sheet: &str) -> Result<Option<PaperSize>>

Get the paper size for a sheet.

pub fn get_page_setup_details( &self, sheet: &str, ) -> Result<(Option<u32>, Option<u32>, Option<u32>)>

Get scale, fit-to-width, and fit-to-height values for a sheet.

Returns (scale, fit_to_width, fit_to_height), each None if not set.

pub fn set_header_footer( &mut self, sheet: &str, header: Option<&str>, footer: Option<&str>, ) -> Result<()>

Set header and footer text for printing.

pub fn get_header_footer( &self, sheet: &str, ) -> Result<(Option<String>, Option<String>)>

Get the header and footer text for a sheet.

pub fn set_print_options( &mut self, sheet: &str, grid_lines: Option<bool>, headings: Option<bool>, h_centered: Option<bool>, v_centered: Option<bool>, ) -> Result<()>

Set print options on a sheet.

pub fn get_print_options( &self, sheet: &str, ) -> Result<(Option<bool>, Option<bool>, Option<bool>, Option<bool>)>

Get print options for a sheet.

Returns (grid_lines, headings, horizontal_centered, vertical_centered).

pub fn insert_page_break(&mut self, sheet: &str, row: u32) -> Result<()>

Insert a horizontal page break before the given 1-based row.

pub fn remove_page_break(&mut self, sheet: &str, row: u32) -> Result<()>

Remove a horizontal page break at the given 1-based row.

pub fn get_page_breaks(&self, sheet: &str) -> Result<Vec<u32>>

Get all row page break positions (1-based row numbers).

pub fn set_cell_hyperlink( &mut self, sheet: &str, cell: &str, link: HyperlinkType, display: Option<&str>, tooltip: Option<&str>, ) -> Result<()>

Set a hyperlink on a cell.

For external URLs and email links, a relationship entry is created in the worksheet’s .rels file. Internal sheet references use only the location attribute without a relationship.

pub fn get_cell_hyperlink( &self, sheet: &str, cell: &str, ) -> Result<Option<HyperlinkInfo>>

Get hyperlink information for a cell.

Returns None if the cell has no hyperlink.

pub fn delete_cell_hyperlink(&mut self, sheet: &str, cell: &str) -> Result<()>

Delete a hyperlink from a cell.

Removes both the hyperlink element from the worksheet XML and any associated relationship entry.

pub fn protect_workbook(&mut self, config: WorkbookProtectionConfig)

Protect the workbook structure and/or windows.

pub fn unprotect_workbook(&mut self)

Remove workbook protection.

pub fn is_workbook_protected(&self) -> bool

Check if the workbook is protected.

pub fn get_theme_color(&self, index: u32, tint: Option<f64>) -> Option<String>

Resolve a theme color by index (0-11) with optional tint. Returns the ARGB hex string (e.g. “FF4472C4”) or None if the index is out of range.

pub fn set_defined_name( &mut self, name: &str, value: &str, scope: Option<&str>, comment: Option<&str>, ) -> Result<()>

Add or update a defined name in the workbook.

If scope is None, the name is workbook-scoped (visible from all sheets). If scope is Some(sheet_name), it is sheet-scoped using the sheet’s 0-based index. If a name with the same name and scope already exists, its value and comment are updated.

pub fn get_defined_name( &self, name: &str, scope: Option<&str>, ) -> Result<Option<DefinedNameInfo>>

Get a defined name by name and scope.

If scope is None, looks for a workbook-scoped name. If scope is Some(sheet_name), looks for a sheet-scoped name. Returns None if no matching defined name is found.

pub fn get_all_defined_names(&self) -> Vec<DefinedNameInfo>

List all defined names in the workbook.

pub fn delete_defined_name( &mut self, name: &str, scope: Option<&str>, ) -> Result<()>

Delete a defined name by name and scope.

Returns an error if the name does not exist for the given scope.

pub fn protect_sheet( &mut self, sheet: &str, config: &SheetProtectionConfig, ) -> Result<()>

Protect a sheet with optional password and permission settings.

Delegates to crate::sheet::protect_sheet after looking up the sheet.

pub fn unprotect_sheet(&mut self, sheet: &str) -> Result<()>

Remove sheet protection.

pub fn is_sheet_protected(&self, sheet: &str) -> Result<bool>

Check if a sheet is protected.

impl Workbook

pub fn new() -> Self

Create a new empty workbook containing a single empty sheet named “Sheet1”.

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self>

Open an existing .xlsx file from disk.

If the file is encrypted (CFB container), returns Error::FileEncrypted. Use [Workbook::open_with_password] instead.

pub fn save<P: AsRef<Path>>(&self, path: P) -> Result<()>

Save the workbook to a .xlsx file at the given path.

pub fn save_to_buffer(&self) -> Result<Vec<u8>>

Serialize the workbook to an in-memory .xlsx buffer.

pub fn open_from_buffer(data: &[u8]) -> Result<Self>

Open a workbook from an in-memory .xlsx buffer.

impl Workbook

pub fn sheet_names(&self) -> Vec<&str>

Return the names of all sheets in workbook order.

pub fn new_sheet(&mut self, name: &str) -> Result<usize>

Create a new empty sheet with the given name. Returns the 0-based sheet index.

pub fn delete_sheet(&mut self, name: &str) -> Result<()>

Delete a sheet by name.

pub fn set_sheet_name(&mut self, old_name: &str, new_name: &str) -> Result<()>

Rename a sheet.

pub fn copy_sheet(&mut self, source: &str, target: &str) -> Result<usize>

Copy a sheet, returning the 0-based index of the new copy.

pub fn get_sheet_index(&self, name: &str) -> Option<usize>

Get a sheet’s 0-based index by name. Returns None if not found.

pub fn get_active_sheet(&self) -> &str

Get the name of the active sheet.

pub fn set_active_sheet(&mut self, name: &str) -> Result<()>

Set the active sheet by name.

pub fn new_stream_writer(&self, sheet_name: &str) -> Result<StreamWriter>

Create a StreamWriter for a new sheet.

The sheet will be added to the workbook when the StreamWriter is applied via apply_stream_writer.

pub fn apply_stream_writer(&mut self, writer: StreamWriter) -> Result<usize>

Apply a completed StreamWriter to the workbook, adding it as a new sheet.

Returns the 0-based index of the new sheet.

pub fn insert_rows( &mut self, sheet: &str, start_row: u32, count: u32, ) -> Result<()>

Insert count empty rows starting at start_row in the named sheet.

pub fn remove_row(&mut self, sheet: &str, row: u32) -> Result<()>

Remove a single row from the named sheet, shifting rows below it up.

pub fn duplicate_row(&mut self, sheet: &str, row: u32) -> Result<()>

Duplicate a row, inserting the copy directly below.

pub fn set_row_height( &mut self, sheet: &str, row: u32, height: f64, ) -> Result<()>

Set the height of a row in points.

pub fn get_row_height(&self, sheet: &str, row: u32) -> Result<Option<f64>>

Get the height of a row.

pub fn set_row_visible( &mut self, sheet: &str, row: u32, visible: bool, ) -> Result<()>

Set the visibility of a row.

pub fn get_row_visible(&self, sheet: &str, row: u32) -> Result<bool>

Get the visibility of a row. Returns true if visible (not hidden).

pub fn set_row_outline_level( &mut self, sheet: &str, row: u32, level: u8, ) -> Result<()>

Set the outline level of a row.

pub fn get_row_outline_level(&self, sheet: &str, row: u32) -> Result<u8>

Get the outline level of a row. Returns 0 if not set.

pub fn set_row_style( &mut self, sheet: &str, row: u32, style_id: u32, ) -> Result<()>

Set the style for an entire row.

The style_id must be a valid index in cellXfs (returned by add_style).

pub fn get_row_style(&self, sheet: &str, row: u32) -> Result<u32>

Get the style ID for a row. Returns 0 (default) if not set.

pub fn get_rows( &self, sheet: &str, ) -> Result<Vec<(u32, Vec<(String, CellValue)>)>>

Get all rows with their data from a sheet.

Returns a Vec of (row_number, Vec<(column_name, CellValue)>) tuples. Only rows that contain at least one cell are included (sparse).

pub fn get_cols( &self, sheet: &str, ) -> Result<Vec<(String, Vec<(u32, CellValue)>)>>

Get all columns with their data from a sheet.

Returns a Vec of (column_name, Vec<(row_number, CellValue)>) tuples. Only columns that have data are included (sparse).

pub fn set_col_width( &mut self, sheet: &str, col: &str, width: f64, ) -> Result<()>

Set the width of a column.

pub fn get_col_width(&self, sheet: &str, col: &str) -> Result<Option<f64>>

Get the width of a column.

pub fn set_col_visible( &mut self, sheet: &str, col: &str, visible: bool, ) -> Result<()>

Set the visibility of a column.

pub fn get_col_visible(&self, sheet: &str, col: &str) -> Result<bool>

Get the visibility of a column. Returns true if visible (not hidden).

pub fn set_col_outline_level( &mut self, sheet: &str, col: &str, level: u8, ) -> Result<()>

Set the outline level of a column.

pub fn get_col_outline_level(&self, sheet: &str, col: &str) -> Result<u8>

Get the outline level of a column. Returns 0 if not set.

pub fn set_col_style( &mut self, sheet: &str, col: &str, style_id: u32, ) -> Result<()>

Set the style for an entire column.

The style_id must be a valid index in cellXfs (returned by add_style).

pub fn get_col_style(&self, sheet: &str, col: &str) -> Result<u32>

Get the style ID for a column. Returns 0 (default) if not set.

pub fn insert_cols(&mut self, sheet: &str, col: &str, count: u32) -> Result<()>

Insert count columns starting at col in the named sheet.

pub fn remove_col(&mut self, sheet: &str, col: &str) -> Result<()>

Remove a single column from the named sheet.

Trait Implementations

impl Default for Workbook

fn default() -> Self

Returns the “default value” for a type.