Crate rust_xlsxwriter

rust_xlsxwriter is a Rust library for writing Excel files in the xlsx format.

The rust_xlsxwriter crate can be used to write text, numbers, dates and formulas to multiple worksheets in a new Excel 2007+ xlsx file. It has a focus on performance and on fidelity with the file format created by Excel. It cannot be used to modify an existing file.

rust_xlsxwriter is a port of the XlsxWriter Python module by the same author. Feature porting is a work in progress. The currently supported features are:

• Support for writing all basic Excel data types.
• Full cell formatting support.
• Formula support, including new Excel 365 dynamic functions.
• Charts.
• Hyperlink support.
• Page/Printing Setup support.
• Merged ranges.
• Conditional formatting.
• Sparklines.
• Worksheet PNG/JPEG/GIF/BMP images.
• Rich multi-format strings.
• Defined names.
• Autofilters.
• Worksheet Tables.

Table of contents

• Tutorial: A getting started and tutorial guide.
• Cookbook: Examples of using rust_xlsxwriter.

• Workbook: The entry point for creating an Excel workbook of worksheets.
• Working with Workbooks: A higher level introduction to creating and working with workbooks.

• Worksheet: The main spreadsheet canvas for writing data and objects to a worksheet.
• Working with Worksheets: A higher level introduction to creating and working with worksheets.

• Chart struct: The interface for creating worksheet charts.
• Working with charts: A higher level introduction to creating and using charts.

• Format: The interface for adding formatting to worksheets and other objects.
• Table: The interface for worksheet tables.
• Image: The interface for images used in worksheets.
• Conditional Formats: Working with conditional formatting in worksheets.
• Sparklines: Working with Sparklines.
• ExcelDateTime: A type to represent dates and times in Excel format.
• Formula: A type for Excel formulas.
• Url: A type for URLs/Hyperlinks used in worksheets.
• DocProperties: The interface used to create an object to represent document metadata properties.

Other external documentation:

• User Guide: Working with the rust_xlsxwriter library.
• Release Notes.
• Roadmap of planned features.

Example

Sample code to generate the Excel file shown above.

use rust_xlsxwriter::*;

fn main() -> Result<(), XlsxError> {
    // Create a new Excel file object.
    let mut workbook = Workbook::new();

    // Create some formats to use in the worksheet.
    let bold_format = Format::new().set_bold();
    let decimal_format = Format::new().set_num_format("0.000");
    let date_format = Format::new().set_num_format("yyyy-mm-dd");
    let merge_format = Format::new()
        .set_border(FormatBorder::Thin)
        .set_align(FormatAlign::Center);

    // Add a worksheet to the workbook.
    let worksheet = workbook.add_worksheet();

    // Set the column width for clarity.
    worksheet.set_column_width(0, 22)?;

    // Write a string without formatting.
    worksheet.write(0, 0, "Hello")?;

    // Write a string with the bold format defined above.
    worksheet.write_with_format(1, 0, "World", &bold_format)?;

    // Write some numbers.
    worksheet.write(2, 0, 1)?;
    worksheet.write(3, 0, 2.34)?;

    // Write a number with formatting.
    worksheet.write_with_format(4, 0, 3.00, &decimal_format)?;

    // Write a formula.
    worksheet.write(5, 0, Formula::new("=SIN(PI()/4)"))?;

    // Write a date.
    let date = ExcelDateTime::from_ymd(2023, 1, 25)?;
    worksheet.write_with_format(6, 0, &date, &date_format)?;

    // Write some links.
    worksheet.write(7, 0, Url::new("https://www.rust-lang.org"))?;
    worksheet.write(8, 0, Url::new("https://www.rust-lang.org").set_text("Rust"))?;

    // Write some merged cells.
    worksheet.merge_range(9, 0, 9, 1, "Merged cells", &merge_format)?;

    // Insert an image.
    let image = Image::new("examples/rust_logo.png")?;
    worksheet.insert_image(1, 2, &image)?;

    // Save the file to disk.
    workbook.save("demo.xlsx")?;

    Ok(())
}

Crate Features

The following is a list of the features supports by the rust_xlsxwriter crate:

• default: Includes all the standard functionality. Has dependencies on zip, regex and lazy_static.
• serde: Adds supports for Serde serialization. This is off by default.
• chrono: Adds supports for Chrono date/time types to the API. This is off by default.
• zlib: Adds a dependency on zlib and a C compiler. This includes the same features as default but is 1.5x faster for large files.
• polars: Add support for mapping between PolarsError and rust_xlsxwriter::XlsxError to make code that handles both types of error easier to write.
• wasm: Adds a dependency on js-sys and wasm-bindgen to allow compilation for wasm/JavaScript targets.

Modules

• chart
  Working with Charts
• conditional_format
  Working with Conditional Formats
• cookbook
  A cookbook of example programs using rust_xlsxwriter.
• serializerserde
  Working with Serde
• sparkline
  Working with Sparklines
• tutorial
  A getting started tutorial for rust_xlsxwriter.
• utility
  Utility functions for rust_xlsxwriter.
• workbook
  Working with Workbooks
• worksheet
  Working with Worksheets

Structs

• DocProperties
  The DocProperties struct is used to create an object to represent document metadata properties.
• ExcelDateTime
  The ExcelDateTime struct is used to represent an Excel date and/or time.
• FilterCondition
  The FilterCondition struct is used to define autofilter rules.
• Format
  The Format struct is used to define cell formatting for data in a worksheet.
• Formula
  The Formula struct is used to define a worksheet formula.
• Image
  The Image struct is used to create an object to represent an image that can be inserted into a worksheet.
• ProtectionOptions
  The ProtectionOptions struct is use to set protected elements in a worksheet.
• Table
  The Table struct represents a worksheet Table.
• TableColumn
  The TableColumn struct represents a table column.
• Url
  The Url struct is used to define a worksheet url.

Enums

• Color
  The Color enum defines Excel colors that can be used throughout the rust_xlsxwriter APIs.
• FilterCriteria
  The FilterCriteria enum defines logical filter criteria used in an autofilter.
• FormatAlign
  The FormatAlign enum defines the vertical and horizontal alignment properties of a Format.
• FormatBorder
  The FormatBorder enum defines the Excel border types that can be added to a Format pattern.
• FormatDiagonalBorder
  The FormatDiagonalBorder enum defines Format diagonal border types.
• FormatPattern
  The FormatPattern enum defines the Excel pattern types that can be added to a Format.
• FormatScript
  The FormatScript enum defines the Format font superscript and subscript properties.
• FormatUnderline
  The FormatUnderline enum defines the font underline type in a Format.
• HeaderImagePosition
  The HeaderImagePosition enum defines the image position in a header or footer.
• ObjectMovement
  The ObjectMovement enum defines the movement of worksheet objects such as images and charts.
• TableFunction
  The TableFunction enum defines functions for worksheet table total rows.
• TableStyle
  The TableStyle enum defines the worksheet table styles.
• XlsxError
  The XlsxError enum defines the error values for the rust_xlsxwriter library.

Traits

• IntoColor
  Trait to map types into an Color value.
• IntoCustomDateTimeUtc
  Trait to map user date types to an Excel UTC date.
• IntoCustomProperty
  Trait to map different Rust types into Excel data types used in custom document properties.
• IntoExcelDateTime
  Trait to map user date/time types to an Excel serial datetimes.
• IntoFilterData
  Trait to map different Rust types into Excel data types used in filters.

Derive Macros

• XlsxSerializeserde
  The XlsxSerialize derived trait is used in conjunction with rust_xlsxwriter serialization.