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_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.

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.