Struct Workbook 

pub struct Workbook {
    pub sheets: Vec<Sheet>,
    pub defined_names: Vec<DefinedName>,
    pub properties: DocumentProperties,
    pub protection: Option<WorkbookProtection>,
    pub write_protection: Option<WriteProtection>,
    pub active_tab: Option<usize>,
    pub external_links: Vec<ExternalWorkbookLink>,
    pub vba_project: Option<Vec<u8>>,
    pub calculation: Option<CalculationProperties>,
    pub table_styles: Vec<TableStyle>,
    pub named_cell_styles: Vec<NamedCellStyle>,
}

A .xlsx workbook: a sequence of sheets, in the order they appear in Excel’s own sheet tabs.

Fields

sheets: Vec<Sheet>

The sheets that make up this workbook, in order.

defined_names: Vec<DefinedName>

Named ranges/formulas/constants defined on this workbook (<definedNames>/<definedName>, CT_DefinedNames/CT_DefinedName), in order. Unlike a sheet, this lives at the workbook level even for a name scoped to a single sheet (see DefinedName::local_sheet_id).

properties: DocumentProperties

Document metadata (docProps/core.xml/docProps/app.xml). Both parts are always written by this crate (they’re required for a strictly valid package), but before this point every field in them was left empty/boilerplate.

protection: Option<WorkbookProtection>

Workbook structure protection (<workbookProtection>, CT_WorkbookProtection). Distinct from Sheet::protection: this locks whether sheets can be added/renamed/hidden/reordered/deleted, not cell editing within a sheet.

write_protection: Option<WriteProtection>

Write-protection / “read-only recommended” (<fileSharing>, CT_FileSharing). Distinct from protection (<workbookProtection>, point 26, which locks structure): this instead controls the “This file should be opened as read-only” prompt Excel shows when opening the file, and/or the legacy 16-bit write-reservation password some older workflows still use. Confirmed via sml.xsd: CT_Workbook’s sequence puts fileSharing? before workbookPr?/ workbookProtection?/bookViews?, i.e. as the very first possible child of <workbook>.

active_tab: Option<usize>

The 0-based index into sheets of the sheet shown as active/selected when the workbook is opened (<bookViews><workbookView activeTab="..">). None leaves Excel’s own default (the first sheet).

external_links: Vec<ExternalWorkbookLink>

References to other workbooks used by this workbook’s formulas (<externalReferences> + one xl/externalLinks/externalLinkN.xml part per entry, CT_ExternalReference). Storage only, same posture as this crate’s own formula text: nothing here resolves or evaluates a reference into the other workbook’s actual values.

vba_project: Option<Vec<u8>>

A VBA project’s raw compiled bytes (xl/vbaProject.bin), if this workbook carries macros. Preserved opaquely: this crate can round-trip an existing macro-enabled workbook’s vbaProject.bin unchanged but cannot create, parse, or modify VBA source from scratch; the OLE2/ CFB container format vbaProject.bin is internally structured in isn’t decoded at all. When Some, Workbook::write_to switches the workbook part’s content type to the macro-enabled variant (..sheet.macroEnabled.main+xml) — the caller is still responsible for using a .xlsm file name, this crate has no notion of file extensions.

calculation: Option<CalculationProperties>

Workbook-wide calculation properties (<calcPr>, CT_CalcPr). None leaves Excel’s own default (automatic recalculation, no iterative calculation).

table_styles: Vec<TableStyle>

Custom table style definitions (xl/styles.xml’s <tableStyles>), referenced by name from any sheet’s ExcelTable::table_style_name. Workbook-wide (styles.xml is a single shared part), same posture as defined_names living here rather than per-sheet even for a sheet-scoped name.

named_cell_styles: Vec<NamedCellStyle>

Named cell styles (xl/styles.xml’s <cellStyles>/<cellStyleXfs>, CT_CellStyles/CT_CellStyleXfs): the “Cell Styles” gallery Excel’s Home ribbon shows (Good/ Bad/Neutral, Heading 1-4, Input/Output/Calculation, Currency/Percent/Comma..). Before this point every cellXfs entry this crate wrote implicitly pointed at a single, hardcoded "Normal" cellStyleXfs entry (xfId="0") — a cell format that set CellFormat::named_style had no way to actually link back to one of these named entries, so the association was silently lost on write. A CellFormat used anywhere in this workbook (cell, row/column default..) that sets named_style to a name found here gets that entry’s index written as its cellXfs xfId, instead of the default 0; a name not found here silently falls back to 0 ("Normal"), same “best-effort, not validated” posture as ExcelTable::table_style_name referencing a name not in this same list. Workbook-wide (styles.xml is a single shared part), same posture as table_styles/defined_names living here rather than per-sheet.

Implementations

impl Workbook

pub fn new() -> Workbook

Creates an empty workbook (no sheets).

Examples found in repository

examples/hello_world_xlsx.rs (line 18)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("hello_world.xlsx");

    // `Workbook` and `Row` both come from `office_toolkit::prelude`.
    // `Row::with_text` puts a single text cell in column A.
    let workbook = Workbook::new()
        .with_sheet(Sheet::new("Sheet1").with_row(Row::new().with_text("Hello, world!")));
    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());

    // Read the file back to confirm it is a valid .xlsx.
    let reopened = Workbook::open_file(&path)?;
    let cell_a1 = &reopened.sheets[0].rows[0].cells[0].value;
    println!("Read back A1: {cell_a1:?}");
    assert!(matches!(cell_a1, CellValue::Text(text) if text == "Hello, world!"));

    Ok(())
}

examples/xlsx_images_and_charts.rs (line 43)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_images_and_charts.xlsx");
    let image_bytes = std::fs::read(image_fixture_path())?;

    let picture = SheetPicture::new(image_bytes, PictureFormat::Png).with_name("Test image");
    let picture_sheet = Sheet::new("Picture")
        .with_row(Row::new().with_text("The picture is anchored to cell A1:"))
        .with_drawing(SheetDrawing::new().with_anchor(DrawingAnchor::new(
            CellAnchorPoint::new(0, 1),
            CellAnchorPoint::new(2, 6),
            DrawingObject::Picture(Box::new(picture)),
        )));

    let chart = SheetChart::new(sample_chart_space()).with_name("Quarterly revenue");
    let chart_sheet = Sheet::new("Chart")
        .with_row(Row::new().with_text("A bar chart is anchored below:"))
        .with_drawing(SheetDrawing::new().with_anchor(DrawingAnchor::new(
            CellAnchorPoint::new(0, 1),
            CellAnchorPoint::new(6, 16),
            DrawingObject::Chart(Box::new(chart)),
        )));

    let workbook = Workbook::new()
        .with_sheet(picture_sheet)
        .with_sheet(chart_sheet);
    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

examples/xlsx_protection.rs (line 31)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_protection.xlsx");

    let sheet_protection_sheet = Sheet::new("Sheet protection")
        .with_row(Row::new().with_text("Locked: this sheet is protected with a password."))
        .with_protection(SheetProtection::with_password("secret"));

    let protected_range_sheet = Sheet::new("Protected range")
        .with_row(
            Row::new()
                .with_text("A1 is protected; B1 stays editable via a named unprotected range."),
        )
        .with_protection(SheetProtection::locked())
        .with_protected_range(ProtectedRange::new("EditableArea", "B1:B1").with_password("secret"));

    let workbook = Workbook::new()
        .with_write_protection(
            WriteProtection::recommended()
                .with_user_name("Author")
                .with_password("secret"),
        )
        .with_sheet(sheet_protection_sheet)
        .with_sheet(protected_range_sheet);

    // `Workbook.protection` (structure protection: locking sheet
    // add/rename/hide/reorder/delete) has no `with_*` builder — it's set
    // directly, like any other public field.
    let workbook = Workbook {
        protection: Some(WorkbookProtection::locked().with_lock_windows(true)),
        ..workbook
    };

    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

examples/xlsx_print_and_views.rs (line 48)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_print_and_views.xlsx");

    let print_setup_sheet = Sheet::new("Print setup")
        .with_row(Row::new().with_text("Header").with_text("Header"))
        .with_row(Row::new().with_text("Data").with_number(1.0))
        .with_print_settings(
            PrintSettings::new()
                .with_print_area("A1:B2")
                .with_repeat_rows("1:1")
                .with_fit_to_width(1)
                .with_fit_to_height(0)
                .with_scale(100)
                .with_orientation(PageOrientation::Landscape)
                .with_header("&CCompany Report")
                .with_footer("&LPage &P of &N"),
        );

    let view_options_sheet = Sheet::new("View options")
        .with_row(Row::new().with_text("Zoomed, colored tab, no gridlines"))
        .with_zoom_scale(150)
        .with_tab_color("FFC00000")
        .with_show_grid_lines(false)
        .with_show_row_col_headers(false)
        .with_show_zeros(false)
        .with_right_to_left(false)
        .with_active_cell("A1")
        .with_default_column_width(12.0)
        .with_default_row_height(18.0);

    let hidden_sheet = Sheet::new("Hidden sheet")
        .with_row(Row::new().with_text("Not shown in the tab bar unless unhidden."))
        .with_visibility(SheetVisibility::Hidden);

    let workbook = Workbook::new()
        .with_sheet(print_setup_sheet)
        .with_sheet(view_options_sheet)
        .with_sheet(hidden_sheet);

    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

examples/xlsx_structure_and_layout.rs (line 66)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_structure_and_layout.xlsx");

    let merged_sheet = Sheet::new("Merged cells")
        .with_row(Row::new().with_text("This title spans three columns"))
        .with_merged_range("A1:C1");

    let columns_sheet = Sheet::new("Columns")
        .with_row(
            Row::new()
                .with_cell(Cell::text("Wide"))
                .with_cell(Cell::text("Hidden"))
                .with_cell(Cell::text("Grouped")),
        )
        .with_column_setting(ColumnSetting::new(0).with_width(30.0))
        .with_column_setting(ColumnSetting::new(1).with_hidden(true))
        .with_column_setting(
            ColumnSetting::new(2)
                .with_outline_level(1)
                .with_collapsed(false),
        );

    let rows_sheet = Sheet::new("Rows")
        .with_row(Row::new().with_text("Normal row"))
        .with_row(Row::new().with_text("Taller row").with_height(30.0))
        .with_row(Row::new().with_text("Hidden row").with_hidden(true))
        .with_row(
            Row::new()
                .with_text("Grouped detail row")
                .with_outline_level(1),
        );

    let frozen_panes_sheet = Sheet::new("Frozen panes")
        .with_row(
            Row::new()
                .with_cell(Cell::text("Frozen header"))
                .with_cell(Cell::text("Frozen header")),
        )
        .with_row(
            Row::new()
                .with_cell(Cell::text("Scrolling data"))
                .with_cell(Cell::number(1.0)),
        )
        .with_freeze_panes(FreezePane::new(1, 1));

    let page_breaks_sheet = Sheet::new("Page breaks")
        .with_row(Row::new().with_text("Above this row: page break"))
        .with_row(Row::new().with_text("Below the break"))
        .with_row_break(1)
        .with_column_break(0)
        .with_outline_summary_below(false)
        .with_outline_summary_right(false);

    let workbook = Workbook::new()
        .with_sheet(merged_sheet)
        .with_sheet(columns_sheet)
        .with_sheet(rows_sheet)
        .with_sheet(frozen_panes_sheet)
        .with_sheet(page_breaks_sheet);

    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

examples/xlsx_workbook_metadata.rs (line 53)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_workbook_metadata.xlsx");

    let named_ranges_sheet = Sheet::new("Named ranges")
        .with_row(Row::new().with_text("Tax rate").with_number(0.0825))
        .with_row(Row::new().with_cell(Cell::formula("TaxRate*100").with_cached_value(8.25)));

    let calculation_sheet = Sheet::new("Calculation").with_row(
        Row::new().with_text("Set to manual recalculation with iterative calculation enabled."),
    );

    let scenarios_sheet = Sheet::new("Scenarios")
        .with_row(Row::new().with_text("Revenue").with_number(100_000.0))
        .with_row(Row::new().with_text("Cost").with_number(60_000.0))
        .with_scenario(
            Scenario::new("Best case")
                .with_input("B1", "150000")
                .with_input("B2", "55000")
                .with_comment("Optimistic projection"),
        )
        .with_scenario(
            Scenario::new("Worst case")
                .with_input("B1", "70000")
                .with_input("B2", "65000"),
        );

    let auto_filter_sheet = Sheet::new("Autofilter criteria")
        .with_row(Row::new().with_text("Region"))
        .with_row(Row::new().with_text("North"))
        .with_row(Row::new().with_text("South"))
        .with_auto_filter_range("A1:A3")
        .with_auto_filter_column(AutoFilterColumn::new(0, vec!["North".to_string()]));

    let ignored_errors_sheet = Sheet::new("Ignored errors")
        .with_row(Row::new().with_text("123")) // a number stored as text — normally flagged by Excel
        .with_ignored_error(IgnoredError::new("A1:A1").with_number_stored_as_text(true));

    let workbook = Workbook::new()
        .with_defined_name(DefinedName::new("TaxRate", "'Named ranges'!$B$1"))
        .with_calculation(
            CalculationProperties::new()
                .with_mode(CalculationMode::Manual)
                .with_iterate(true),
        )
        .with_sheet(named_ranges_sheet)
        .with_sheet(calculation_sheet)
        .with_sheet(scenarios_sheet)
        .with_sheet(auto_filter_sheet)
        .with_sheet(ignored_errors_sheet);

    // `Workbook.properties` has no `with_*` builder — it's set directly,
    // like any other public field.
    let properties = DocumentProperties::new()
        .with_title("Metadata example")
        .with_author("Example Author")
        .with_subject("Workbook-level features")
        .with_custom_property(
            "ProjectCode",
            CustomPropertyValue::Text("XLSX-META".to_string()),
        );
    let workbook = Workbook {
        properties,
        ..workbook
    };

    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

Additional examples can be found in:

• examples/xlsx_tables.rs
• examples/xlsx_conditional_formatting_and_validation.rs
• examples/xlsx_rich_data.rs
• examples/xlsx_cell_formatting.rs

pub fn with_sheet(self, sheet: Sheet) -> Workbook

Appends a sheet and returns the workbook for chaining.

Examples found in repository

examples/hello_world_xlsx.rs (line 19)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("hello_world.xlsx");

    // `Workbook` and `Row` both come from `office_toolkit::prelude`.
    // `Row::with_text` puts a single text cell in column A.
    let workbook = Workbook::new()
        .with_sheet(Sheet::new("Sheet1").with_row(Row::new().with_text("Hello, world!")));
    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());

    // Read the file back to confirm it is a valid .xlsx.
    let reopened = Workbook::open_file(&path)?;
    let cell_a1 = &reopened.sheets[0].rows[0].cells[0].value;
    println!("Read back A1: {cell_a1:?}");
    assert!(matches!(cell_a1, CellValue::Text(text) if text == "Hello, world!"));

    Ok(())
}

examples/xlsx_images_and_charts.rs (line 44)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_images_and_charts.xlsx");
    let image_bytes = std::fs::read(image_fixture_path())?;

    let picture = SheetPicture::new(image_bytes, PictureFormat::Png).with_name("Test image");
    let picture_sheet = Sheet::new("Picture")
        .with_row(Row::new().with_text("The picture is anchored to cell A1:"))
        .with_drawing(SheetDrawing::new().with_anchor(DrawingAnchor::new(
            CellAnchorPoint::new(0, 1),
            CellAnchorPoint::new(2, 6),
            DrawingObject::Picture(Box::new(picture)),
        )));

    let chart = SheetChart::new(sample_chart_space()).with_name("Quarterly revenue");
    let chart_sheet = Sheet::new("Chart")
        .with_row(Row::new().with_text("A bar chart is anchored below:"))
        .with_drawing(SheetDrawing::new().with_anchor(DrawingAnchor::new(
            CellAnchorPoint::new(0, 1),
            CellAnchorPoint::new(6, 16),
            DrawingObject::Chart(Box::new(chart)),
        )));

    let workbook = Workbook::new()
        .with_sheet(picture_sheet)
        .with_sheet(chart_sheet);
    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

examples/xlsx_protection.rs (line 37)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_protection.xlsx");

    let sheet_protection_sheet = Sheet::new("Sheet protection")
        .with_row(Row::new().with_text("Locked: this sheet is protected with a password."))
        .with_protection(SheetProtection::with_password("secret"));

    let protected_range_sheet = Sheet::new("Protected range")
        .with_row(
            Row::new()
                .with_text("A1 is protected; B1 stays editable via a named unprotected range."),
        )
        .with_protection(SheetProtection::locked())
        .with_protected_range(ProtectedRange::new("EditableArea", "B1:B1").with_password("secret"));

    let workbook = Workbook::new()
        .with_write_protection(
            WriteProtection::recommended()
                .with_user_name("Author")
                .with_password("secret"),
        )
        .with_sheet(sheet_protection_sheet)
        .with_sheet(protected_range_sheet);

    // `Workbook.protection` (structure protection: locking sheet
    // add/rename/hide/reorder/delete) has no `with_*` builder — it's set
    // directly, like any other public field.
    let workbook = Workbook {
        protection: Some(WorkbookProtection::locked().with_lock_windows(true)),
        ..workbook
    };

    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

examples/xlsx_print_and_views.rs (line 49)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_print_and_views.xlsx");

    let print_setup_sheet = Sheet::new("Print setup")
        .with_row(Row::new().with_text("Header").with_text("Header"))
        .with_row(Row::new().with_text("Data").with_number(1.0))
        .with_print_settings(
            PrintSettings::new()
                .with_print_area("A1:B2")
                .with_repeat_rows("1:1")
                .with_fit_to_width(1)
                .with_fit_to_height(0)
                .with_scale(100)
                .with_orientation(PageOrientation::Landscape)
                .with_header("&CCompany Report")
                .with_footer("&LPage &P of &N"),
        );

    let view_options_sheet = Sheet::new("View options")
        .with_row(Row::new().with_text("Zoomed, colored tab, no gridlines"))
        .with_zoom_scale(150)
        .with_tab_color("FFC00000")
        .with_show_grid_lines(false)
        .with_show_row_col_headers(false)
        .with_show_zeros(false)
        .with_right_to_left(false)
        .with_active_cell("A1")
        .with_default_column_width(12.0)
        .with_default_row_height(18.0);

    let hidden_sheet = Sheet::new("Hidden sheet")
        .with_row(Row::new().with_text("Not shown in the tab bar unless unhidden."))
        .with_visibility(SheetVisibility::Hidden);

    let workbook = Workbook::new()
        .with_sheet(print_setup_sheet)
        .with_sheet(view_options_sheet)
        .with_sheet(hidden_sheet);

    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

examples/xlsx_structure_and_layout.rs (line 67)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_structure_and_layout.xlsx");

    let merged_sheet = Sheet::new("Merged cells")
        .with_row(Row::new().with_text("This title spans three columns"))
        .with_merged_range("A1:C1");

    let columns_sheet = Sheet::new("Columns")
        .with_row(
            Row::new()
                .with_cell(Cell::text("Wide"))
                .with_cell(Cell::text("Hidden"))
                .with_cell(Cell::text("Grouped")),
        )
        .with_column_setting(ColumnSetting::new(0).with_width(30.0))
        .with_column_setting(ColumnSetting::new(1).with_hidden(true))
        .with_column_setting(
            ColumnSetting::new(2)
                .with_outline_level(1)
                .with_collapsed(false),
        );

    let rows_sheet = Sheet::new("Rows")
        .with_row(Row::new().with_text("Normal row"))
        .with_row(Row::new().with_text("Taller row").with_height(30.0))
        .with_row(Row::new().with_text("Hidden row").with_hidden(true))
        .with_row(
            Row::new()
                .with_text("Grouped detail row")
                .with_outline_level(1),
        );

    let frozen_panes_sheet = Sheet::new("Frozen panes")
        .with_row(
            Row::new()
                .with_cell(Cell::text("Frozen header"))
                .with_cell(Cell::text("Frozen header")),
        )
        .with_row(
            Row::new()
                .with_cell(Cell::text("Scrolling data"))
                .with_cell(Cell::number(1.0)),
        )
        .with_freeze_panes(FreezePane::new(1, 1));

    let page_breaks_sheet = Sheet::new("Page breaks")
        .with_row(Row::new().with_text("Above this row: page break"))
        .with_row(Row::new().with_text("Below the break"))
        .with_row_break(1)
        .with_column_break(0)
        .with_outline_summary_below(false)
        .with_outline_summary_right(false);

    let workbook = Workbook::new()
        .with_sheet(merged_sheet)
        .with_sheet(columns_sheet)
        .with_sheet(rows_sheet)
        .with_sheet(frozen_panes_sheet)
        .with_sheet(page_breaks_sheet);

    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

examples/xlsx_workbook_metadata.rs (line 60)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_workbook_metadata.xlsx");

    let named_ranges_sheet = Sheet::new("Named ranges")
        .with_row(Row::new().with_text("Tax rate").with_number(0.0825))
        .with_row(Row::new().with_cell(Cell::formula("TaxRate*100").with_cached_value(8.25)));

    let calculation_sheet = Sheet::new("Calculation").with_row(
        Row::new().with_text("Set to manual recalculation with iterative calculation enabled."),
    );

    let scenarios_sheet = Sheet::new("Scenarios")
        .with_row(Row::new().with_text("Revenue").with_number(100_000.0))
        .with_row(Row::new().with_text("Cost").with_number(60_000.0))
        .with_scenario(
            Scenario::new("Best case")
                .with_input("B1", "150000")
                .with_input("B2", "55000")
                .with_comment("Optimistic projection"),
        )
        .with_scenario(
            Scenario::new("Worst case")
                .with_input("B1", "70000")
                .with_input("B2", "65000"),
        );

    let auto_filter_sheet = Sheet::new("Autofilter criteria")
        .with_row(Row::new().with_text("Region"))
        .with_row(Row::new().with_text("North"))
        .with_row(Row::new().with_text("South"))
        .with_auto_filter_range("A1:A3")
        .with_auto_filter_column(AutoFilterColumn::new(0, vec!["North".to_string()]));

    let ignored_errors_sheet = Sheet::new("Ignored errors")
        .with_row(Row::new().with_text("123")) // a number stored as text — normally flagged by Excel
        .with_ignored_error(IgnoredError::new("A1:A1").with_number_stored_as_text(true));

    let workbook = Workbook::new()
        .with_defined_name(DefinedName::new("TaxRate", "'Named ranges'!$B$1"))
        .with_calculation(
            CalculationProperties::new()
                .with_mode(CalculationMode::Manual)
                .with_iterate(true),
        )
        .with_sheet(named_ranges_sheet)
        .with_sheet(calculation_sheet)
        .with_sheet(scenarios_sheet)
        .with_sheet(auto_filter_sheet)
        .with_sheet(ignored_errors_sheet);

    // `Workbook.properties` has no `with_*` builder — it's set directly,
    // like any other public field.
    let properties = DocumentProperties::new()
        .with_title("Metadata example")
        .with_author("Example Author")
        .with_subject("Workbook-level features")
        .with_custom_property(
            "ProjectCode",
            CustomPropertyValue::Text("XLSX-META".to_string()),
        );
    let workbook = Workbook {
        properties,
        ..workbook
    };

    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

Additional examples can be found in:

• examples/xlsx_tables.rs
• examples/xlsx_conditional_formatting_and_validation.rs
• examples/xlsx_rich_data.rs
• examples/xlsx_cell_formatting.rs

pub fn add_sheet(&mut self, name: impl Into<String>) -> &mut Sheet

Appends an empty sheet with the given name and returns a mutable reference to it, to build it up in place (e.g. workbook.add_sheet("Feuil1").write_cell(1, 1, Cell::text("Hi"))). A &mut self counterpart to Self::with_sheet, for building a workbook sheet-by-sheet in a loop without the consuming builder’s workbook = workbook.with_sheet(..) reassignment on every iteration.

pub fn with_defined_name(self, defined_name: DefinedName) -> Workbook

Appends a defined name and returns the workbook for chaining.

Examples found in repository

examples/xlsx_workbook_metadata.rs (line 54)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_workbook_metadata.xlsx");

    let named_ranges_sheet = Sheet::new("Named ranges")
        .with_row(Row::new().with_text("Tax rate").with_number(0.0825))
        .with_row(Row::new().with_cell(Cell::formula("TaxRate*100").with_cached_value(8.25)));

    let calculation_sheet = Sheet::new("Calculation").with_row(
        Row::new().with_text("Set to manual recalculation with iterative calculation enabled."),
    );

    let scenarios_sheet = Sheet::new("Scenarios")
        .with_row(Row::new().with_text("Revenue").with_number(100_000.0))
        .with_row(Row::new().with_text("Cost").with_number(60_000.0))
        .with_scenario(
            Scenario::new("Best case")
                .with_input("B1", "150000")
                .with_input("B2", "55000")
                .with_comment("Optimistic projection"),
        )
        .with_scenario(
            Scenario::new("Worst case")
                .with_input("B1", "70000")
                .with_input("B2", "65000"),
        );

    let auto_filter_sheet = Sheet::new("Autofilter criteria")
        .with_row(Row::new().with_text("Region"))
        .with_row(Row::new().with_text("North"))
        .with_row(Row::new().with_text("South"))
        .with_auto_filter_range("A1:A3")
        .with_auto_filter_column(AutoFilterColumn::new(0, vec!["North".to_string()]));

    let ignored_errors_sheet = Sheet::new("Ignored errors")
        .with_row(Row::new().with_text("123")) // a number stored as text — normally flagged by Excel
        .with_ignored_error(IgnoredError::new("A1:A1").with_number_stored_as_text(true));

    let workbook = Workbook::new()
        .with_defined_name(DefinedName::new("TaxRate", "'Named ranges'!$B$1"))
        .with_calculation(
            CalculationProperties::new()
                .with_mode(CalculationMode::Manual)
                .with_iterate(true),
        )
        .with_sheet(named_ranges_sheet)
        .with_sheet(calculation_sheet)
        .with_sheet(scenarios_sheet)
        .with_sheet(auto_filter_sheet)
        .with_sheet(ignored_errors_sheet);

    // `Workbook.properties` has no `with_*` builder — it's set directly,
    // like any other public field.
    let properties = DocumentProperties::new()
        .with_title("Metadata example")
        .with_author("Example Author")
        .with_subject("Workbook-level features")
        .with_custom_property(
            "ProjectCode",
            CustomPropertyValue::Text("XLSX-META".to_string()),
        );
    let workbook = Workbook {
        properties,
        ..workbook
    };

    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_calculation(self, calculation: CalculationProperties) -> Workbook

Sets this workbook’s calculation properties and returns it for chaining.

Examples found in repository

examples/xlsx_workbook_metadata.rs (lines 55-59)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_workbook_metadata.xlsx");

    let named_ranges_sheet = Sheet::new("Named ranges")
        .with_row(Row::new().with_text("Tax rate").with_number(0.0825))
        .with_row(Row::new().with_cell(Cell::formula("TaxRate*100").with_cached_value(8.25)));

    let calculation_sheet = Sheet::new("Calculation").with_row(
        Row::new().with_text("Set to manual recalculation with iterative calculation enabled."),
    );

    let scenarios_sheet = Sheet::new("Scenarios")
        .with_row(Row::new().with_text("Revenue").with_number(100_000.0))
        .with_row(Row::new().with_text("Cost").with_number(60_000.0))
        .with_scenario(
            Scenario::new("Best case")
                .with_input("B1", "150000")
                .with_input("B2", "55000")
                .with_comment("Optimistic projection"),
        )
        .with_scenario(
            Scenario::new("Worst case")
                .with_input("B1", "70000")
                .with_input("B2", "65000"),
        );

    let auto_filter_sheet = Sheet::new("Autofilter criteria")
        .with_row(Row::new().with_text("Region"))
        .with_row(Row::new().with_text("North"))
        .with_row(Row::new().with_text("South"))
        .with_auto_filter_range("A1:A3")
        .with_auto_filter_column(AutoFilterColumn::new(0, vec!["North".to_string()]));

    let ignored_errors_sheet = Sheet::new("Ignored errors")
        .with_row(Row::new().with_text("123")) // a number stored as text — normally flagged by Excel
        .with_ignored_error(IgnoredError::new("A1:A1").with_number_stored_as_text(true));

    let workbook = Workbook::new()
        .with_defined_name(DefinedName::new("TaxRate", "'Named ranges'!$B$1"))
        .with_calculation(
            CalculationProperties::new()
                .with_mode(CalculationMode::Manual)
                .with_iterate(true),
        )
        .with_sheet(named_ranges_sheet)
        .with_sheet(calculation_sheet)
        .with_sheet(scenarios_sheet)
        .with_sheet(auto_filter_sheet)
        .with_sheet(ignored_errors_sheet);

    // `Workbook.properties` has no `with_*` builder — it's set directly,
    // like any other public field.
    let properties = DocumentProperties::new()
        .with_title("Metadata example")
        .with_author("Example Author")
        .with_subject("Workbook-level features")
        .with_custom_property(
            "ProjectCode",
            CustomPropertyValue::Text("XLSX-META".to_string()),
        );
    let workbook = Workbook {
        properties,
        ..workbook
    };

    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_table_style(self, table_style: TableStyle) -> Workbook

Appends a custom table style definition and returns the workbook for chaining. See ExcelTable::table_style_name’s doc comment for how a table references one of these by name.

Examples found in repository

examples/xlsx_tables.rs (lines 84-97)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_tables.xlsx");

    let plain_sheet = Sheet::new("Plain table")
        .with_row(Row::new().with_text("Name").with_text("Score"))
        .with_row(Row::new().with_text("Alice").with_number(92.0))
        .with_row(Row::new().with_text("Bob").with_number(87.0))
        .with_table(ExcelTable::new(
            "ScoresTable",
            "A1:B3",
            vec!["Name", "Score"],
        ));

    let calculated_sheet = Sheet::new("Calculated and totals")
        .with_row(
            Row::new()
                .with_text("Item")
                .with_text("Qty")
                .with_text("Unit price")
                .with_text("Line total"),
        )
        .with_row(
            Row::new()
                .with_text("Widget")
                .with_number(3.0)
                .with_number(9.99)
                .with_cell(Cell::formula("B2*C2").with_cached_value(29.97)),
        )
        .with_row(
            Row::new()
                .with_text("Gadget")
                .with_number(2.0)
                .with_number(19.99)
                .with_cell(Cell::formula("B3*C3").with_cached_value(39.98)),
        )
        .with_row(Row::new().with_cell(Cell::text("Total")))
        .with_table(
            ExcelTable::with_columns(
                "OrdersTable",
                "A1:D4",
                vec![
                    TableColumn::new("Item"),
                    TableColumn::new("Qty").with_totals_row_function(TotalsRowFunction::Sum),
                    TableColumn::new("Unit price"),
                    TableColumn::new("Line total")
                        .with_calculated_formula(
                            "OrdersTable[[#This Row],[Qty]]*OrdersTable[[#This Row],[Unit price]]",
                        )
                        .with_totals_row_function(TotalsRowFunction::Sum),
                ],
            )
            .with_totals_row(true),
        );

    let styled_sheet = Sheet::new("Custom style and sort")
        .with_row(Row::new().with_text("City").with_text("Population"))
        .with_row(Row::new().with_text("Springfield").with_number(120_000.0))
        .with_row(Row::new().with_text("Shelbyville").with_number(95_000.0))
        .with_table(
            ExcelTable::new("CitiesTable", "A1:B3", vec!["City", "Population"])
                .with_table_style_name("CustomTableStyle")
                .with_sort_state(
                    SortState::new("A2:B3")
                        .with_condition(SortCondition::new("B2:B3").with_descending(true)),
                ),
        );

    let workbook = Workbook::new()
        .with_table_style(
            TableStyle::new("CustomTableStyle")
                .with_element(TableStyleElement::new(
                    TableStyleElementType::HeaderRow,
                    CellFormat::new()
                        .with_bold(true)
                        .with_fill_color("FF2E74B5")
                        .with_font_color("FFFFFFFF"),
                ))
                .with_element(TableStyleElement::new(
                    TableStyleElementType::FirstRowStripe,
                    CellFormat::new().with_fill_color("FFF2F2F2"),
                )),
        )
        .with_sheet(plain_sheet)
        .with_sheet(calculated_sheet)
        .with_sheet(styled_sheet);

    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_write_protection( self, write_protection: WriteProtection, ) -> Workbook

Sets this workbook’s write-protection and returns it for chaining.

Examples found in repository

examples/xlsx_protection.rs (lines 32-36)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_protection.xlsx");

    let sheet_protection_sheet = Sheet::new("Sheet protection")
        .with_row(Row::new().with_text("Locked: this sheet is protected with a password."))
        .with_protection(SheetProtection::with_password("secret"));

    let protected_range_sheet = Sheet::new("Protected range")
        .with_row(
            Row::new()
                .with_text("A1 is protected; B1 stays editable via a named unprotected range."),
        )
        .with_protection(SheetProtection::locked())
        .with_protected_range(ProtectedRange::new("EditableArea", "B1:B1").with_password("secret"));

    let workbook = Workbook::new()
        .with_write_protection(
            WriteProtection::recommended()
                .with_user_name("Author")
                .with_password("secret"),
        )
        .with_sheet(sheet_protection_sheet)
        .with_sheet(protected_range_sheet);

    // `Workbook.protection` (structure protection: locking sheet
    // add/rename/hide/reorder/delete) has no `with_*` builder — it's set
    // directly, like any other public field.
    let workbook = Workbook {
        protection: Some(WorkbookProtection::locked().with_lock_windows(true)),
        ..workbook
    };

    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_named_cell_style(self, named_cell_style: NamedCellStyle) -> Workbook

Appends a named cell style definition and returns the workbook for chaining. See CellFormat::named_style’s doc comment for how a format references one of these by name.

Examples found in repository

examples/xlsx_cell_formatting.rs (lines 104-109)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("xlsx_cell_formatting.xlsx");

    let borders_sheet =
        Sheet::new("Borders").with_row(
            Row::new()
                .with_cell(Cell::text("Thin all around").with_format(
                    CellFormat::new().with_border(Border::all(BorderStyle::Thin, "FF000000")),
                ))
                .with_cell(Cell::text("Thick bottom only").with_format(
                    CellFormat::new().with_border(
                        Border::new().with_bottom(
                            BorderEdge::new(BorderStyle::Thick).with_color("FFC00000"),
                        ),
                    ),
                )),
        );

    let fills_sheet = Sheet::new("Fills")
        .with_row(Row::new().with_cell(
            Cell::text("Solid fill").with_format(CellFormat::new().with_fill_color("FFFFF2CC")),
        ))
        .with_row(
            Row::new().with_cell(
                Cell::text("Pattern fill").with_format(
                    CellFormat::new().with_pattern_fill(
                        PatternFill::new(PatternType::LightGray)
                            .with_fg_color("FF4472C4")
                            .with_bg_color("FFFFFFFF"),
                    ),
                ),
            ),
        )
        .with_row(
            Row::new().with_cell(Cell::text("Gradient fill").with_format(
                CellFormat::new().with_gradient_fill(GradientFill::new(
                    90.0,
                    vec![
                        GradientStop::new(0.0, "FFFFFFFF"),
                        GradientStop::new(1.0, "FF4472C4"),
                    ],
                )),
            )),
        );

    let fonts_and_alignment_sheet =
        Sheet::new("Fonts and alignment")
            .with_row(
                Row::new().with_cell(
                    Cell::text("Bold, red, 14pt").with_format(
                        CellFormat::new()
                            .with_bold(true)
                            .with_font_size(14.0)
                            .with_font_color("FFC00000"),
                    ),
                ),
            )
            .with_row(
                Row::new().with_cell(
                    Cell::text("Centered both ways").with_format(
                        CellFormat::new()
                            .with_horizontal_alignment(HorizontalAlignment::Center)
                            .with_vertical_alignment(VerticalAlignment::Center),
                    ),
                ),
            )
            .with_row(Row::new().with_cell(
                Cell::text("Indented text").with_format(CellFormat::new().with_indent(2)),
            ));

    let number_formats_sheet = Sheet::new("Number formats")
        .with_row(Row::new().with_cell(
            Cell::number(1234.5).with_format(CellFormat::new().with_number_format("#,##0.00")),
        ))
        .with_row(Row::new().with_cell(
            Cell::number(0.0825).with_format(CellFormat::new().with_number_format("0.00%")),
        ))
        .with_row(Row::new().with_cell(
            Cell::number(1234.5).with_format(CellFormat::new().with_number_format("$#,##0.00")),
        ));

    let named_styles_sheet = Sheet::new("Named styles").with_row(
        Row::new().with_cell(
            Cell::text("Uses a named style")
                .with_format(CellFormat::new().with_named_style("Emphasis")),
        ),
    );

    let workbook = Workbook::new()
        .with_named_cell_style(NamedCellStyle::new(
            "Emphasis",
            CellFormat::new()
                .with_bold(true)
                .with_font_color("FF4472C4"),
        ))
        .with_sheet(borders_sheet)
        .with_sheet(fills_sheet)
        .with_sheet(fonts_and_alignment_sheet)
        .with_sheet(number_formats_sheet)
        .with_sheet(named_styles_sheet);

    workbook.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

impl Workbook

pub fn read_from<R>(reader: R) -> Result<Workbook, Error>

where R: Read + Seek,

Reads a .xlsx package from a seekable byte source.

impl Workbook

pub fn write_to<W>(&self, writer: W) -> Result<W, Error>

where W: Write + Seek,

Writes this workbook out as a valid .xlsx package.

Writes [Content_Types].xml, _rels/.rels, xl/workbook.xml, xl/_rels/workbook.xml.rels, one xl/worksheets/sheetN.xml per sheet, xl/styles.xml, xl/sharedStrings.xml, docProps/core.xml, docProps/app.xml, and xl/theme/theme1.xml (always the fixed default “Office” theme —; this crate has no notion of a customizable theme model, unlike word-ooxml’s Theme). xl/calcChain.xml is still never written — it only matters for formula dependency ordering, which this crate leaves to Excel to recompute on open. xl/vbaProject.bin and xl/externalLinks/externalLinkN.xml are written only when Workbook::vba_project/Workbook::external_links are non-empty.

Trait Implementations

impl Clone for Workbook

fn clone(&self) -> Workbook

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Workbook

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Workbook

fn default() -> Workbook

Returns the “default value” for a type.

impl OpenFile for Workbook

Available on crate feature excel only.

fn open_file(path: impl AsRef<Path>) -> Result<Self>

Reads self from the file at path.

impl PartialEq for Workbook

fn eq(&self, other: &Workbook) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl SaveToFile for Workbook

Available on crate feature excel only.

fn save_to_file(&self, path: impl AsRef<Path>) -> Result<()>

Writes self to the file at path, creating it (or truncating an existing one) as needed.

impl StructuralPartialEq for Workbook