Crate rust_xlsxwriter

Expand description

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 focuses on performance and fidelity with the file format created by Excel. It cannot be used to modify an existing file.

rust_xlsxwriter is a rewrite of the Python XlsxWriter library in Rust by the same author, with additional Rust-like features and APIs. 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.
Data validation.
Cell Notes.
Textboxes.
Checkboxes.
Sparklines.
Worksheet PNG/JPEG/GIF/BMP images.
Rich multi-format strings.
Outline groupings.
Defined names.
Autofilters.
Worksheet Tables.
Support for macros.
Memory optimization mode for writing large files.

§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 with 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.
DataValidation: Working with data validation in worksheets.
Note: Adding Notes to worksheet cells.
Shape: Adding Textbox shapes to worksheets.
Macros: Working with Macros.
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.

Changelog: Release notes and changelog.
Performance: Performance characteristics of rust_xlsxwriter.

§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 supported by the rust_xlsxwriter crate:

default: Includes all the standard functionality. This has a dependency on the zip crate only.
constant_memory: Keeps memory usage to a minimum when writing large files. See Constant Memory Mode.
serde: Adds support for Serde serialization. This is off by default.
chrono: Adds support 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: Adds support for mapping between PolarsError and rust_xlsxwriter::XlsxError to make code that handles both types of errors easier to write. See also polars_excel_writer.
wasm: Adds a dependency on js-sys and wasm-bindgen to allow compilation for wasm/JavaScript targets. See also wasm-xlsxwriter.
rust_decimal: Adds support for writing the rust_decimal Decimal type with Worksheet::write(), provided it can be represented by f64.
ryu: Adds a dependency on ryu. This speeds up writing numeric worksheet cells for large data files. It gives a performance boost above 300,000 numeric cells and can be up to 30% faster than the default number formatting for 5,000,000 numeric cells.

Modules§

changelog: Changelog
chart: Working with Charts
conditional_format: Working with Conditional Formats
cookbook: A cookbook of example programs using rust_xlsxwriter.
macros: Working with VBA Macros
performance: Performance characteristics of 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§

Button: The Button struct represents a worksheet button object.
DataValidation: The DataValidation struct represents a data validation in Excel.
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.
FilterData: The FilterData struct represents data types used in Excel’s filters.
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.
Note: The Note struct represents a worksheet note object.
ProtectionOptions: The ProtectionOptions struct is used to set protected elements in a worksheet.
Shape: The Shape struct represents a worksheet shape object.
ShapeFont: The ShapeFont struct represents the font format for shape objects.
ShapeFormat: The ShapeFormat struct represents formatting for various shape objects.
ShapeGradientFill: The ShapeGradientFill struct represents a gradient fill for a shape element.
ShapeGradientStop: The ShapeGradientStop struct represents a gradient fill data point.
ShapeLine: The ShapeLine struct represents a shape line/border.
ShapePatternFill: The ShapePatternFill struct represents a the pattern fill for a shape element.
ShapeSolidFill: The ShapeSolidFill struct represents a the solid fill for a shape element.
ShapeText: The ShapeText struct represents the text options for a shape element.
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.
DataValidationErrorStyle: The DataValidationErrorStyle enum defines the type of error dialog that is shown when there is and error in a data validation.
DataValidationRule: The DataValidationRule enum defines the data validation rule for DataValidation.
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.
ShapeGradientFillType: The ShapeGradientFillType enum defines the gradient types of a ShapeGradientFill.
ShapeLineDashType: The ShapeLineDashType enum defines the Shape line dash types.
ShapePatternFillType: The ShapePatternFillType enum defines the Shape pattern fill types.
ShapeTextDirection: The ShapeTextDirection enum defines the text direction for Shape text.
ShapeTextHorizontalAlignment: The ShapeTextHorizontalAlignment enum defines the horizontal alignment for Shape text.
ShapeTextVerticalAlignment: The ShapeTextVerticalAlignment enum defines the vertical alignment for Shape text.
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§

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.
IntoDataValidationValue: Trait to map rust types into data validation types
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.
IntoShapeFormat: Trait to map types into a ShapeFormat.

Derive Macros§

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

Crate rust_xlsxwriterCopy item path