Struct polars_excel_writer::xlsx_writer::PolarsXlsxWriter

pub struct PolarsXlsxWriter { /* private fields */ }

PolarsXlsxWriter provides an Excel Xlsx serializer that works with Polars dataframes and which can also interact with the rust_xlsxwriter writing engine that it wraps. This allows simple Excel serialization of worksheets with a straightforward interface but also a high degree of configurability over the output when required.

It is a complimentary interface to the much simpler ExcelWriter which implements the Polars [SerWriter] trait to serialize dataframes, and which is also part of this crate.

ExcelWriter and PolarsXlsxWriter both use the rust_xlsxwriter crate. The rust_xlsxwriter library can only create new files. It cannot read or modify existing files.

PolarsXlsxWriter tries to replicate the interface options provided by the Polars Python write_excel() dataframe method.

Examples

Here is an example of writing a Polars Rust dataframe to an Excel file using PolarsXlsxWriter.

use chrono::prelude::*;
use polars::prelude::*;

fn main() {
    // Create a sample dataframe for the example.
    let df: DataFrame = df!(
        "String" => &["North", "South", "East", "West"],
        "Integer" => &[1, 2, 3, 4],
        "Float" => &[4.0, 5.0, 6.0, 7.0],
        "Time" => &[
            NaiveTime::from_hms_milli_opt(2, 59, 3, 456).unwrap(),
            NaiveTime::from_hms_milli_opt(2, 59, 3, 456).unwrap(),
            NaiveTime::from_hms_milli_opt(2, 59, 3, 456).unwrap(),
            NaiveTime::from_hms_milli_opt(2, 59, 3, 456).unwrap(),
            ],
        "Date" => &[
            NaiveDate::from_ymd_opt(2022, 1, 1).unwrap(),
            NaiveDate::from_ymd_opt(2022, 1, 2).unwrap(),
            NaiveDate::from_ymd_opt(2022, 1, 3).unwrap(),
            NaiveDate::from_ymd_opt(2022, 1, 4).unwrap(),
            ],
        "Datetime" => &[
            NaiveDate::from_ymd_opt(2022, 1, 1).unwrap().and_hms_opt(1, 0, 0).unwrap(),
            NaiveDate::from_ymd_opt(2022, 1, 2).unwrap().and_hms_opt(2, 0, 0).unwrap(),
            NaiveDate::from_ymd_opt(2022, 1, 3).unwrap().and_hms_opt(3, 0, 0).unwrap(),
            NaiveDate::from_ymd_opt(2022, 1, 4).unwrap().and_hms_opt(4, 0, 0).unwrap(),
        ],
    )
    .unwrap();

    example(&df).unwrap();
}

use polars_excel_writer::PolarsXlsxWriter;

fn example(df: &DataFrame) -> PolarsResult<()> {
    let mut xlsx_writer = PolarsXlsxWriter::new();

    xlsx_writer.write_dataframe(df)?;
    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

Interacting with rust_xlsxwriter

The rust_xlsxwriter crate provides a fast native Rust interface for creating Excel files with features such as formatting, formulas, charts, hyperlinks, page setup, merged ranges, image support, rich multi-format strings, autofilters and tables.

PolarsXlsxWriter uses rust_xlsxwriter internally as its Excel writing engine but it can also be used in conjunction with larger rust_xlsxwriter programs to access functionality that it doesn’t provide natively.

For example, say we wanted to write a dataframe to an Excel workbook but also plot the data on an Excel chart. We can use PolarsXlsxWriter crate for the data writing part and rust_xlsxwriter for all the other functionality.

Here is an example that demonstrate this:

use polars::prelude::*;
use polars_excel_writer::PolarsXlsxWriter;
use rust_xlsxwriter::{Chart, ChartType, Workbook};

fn main() -> PolarsResult<()> {
    // Create a sample dataframe using `Polars`
    let df: DataFrame = df!(
        "Data" => &[10, 20, 15, 25, 30, 20],
    )?;

    // Get some dataframe dimensions that we will use for the chart range.
    let row_min = 1; // Skip the header row.
    let row_max = df.height() as u32;

    // Create a new workbook and worksheet using `rust_xlsxwriter`.
    let mut workbook = Workbook::new();
    let worksheet = workbook.add_worksheet();

    // Write the dataframe to the worksheet using `PolarsXlsxWriter`.
    let mut xlsx_writer = PolarsXlsxWriter::new();
    xlsx_writer.write_dataframe_to_worksheet(&df, worksheet, 0, 0)?;

    // Move back to `rust_xlsxwriter` to create a new chart and have it plot the
    // range of the dataframe in the worksheet.
    let mut chart = Chart::new(ChartType::Line);
    chart
        .add_series()
        .set_values(("Sheet1", row_min, 0, row_max, 0));

    // Add the chart to the worksheet.
    worksheet.insert_chart(0, 2, &chart)?;

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

    Ok(())
}

Output file:

The example demonstrates using three different crates to get the required result:

• 1: polars to create/manipulate the dataframe.
• 2a: rust_xlsxwriter to create an Excel workbook and worksheet.
• 3: polars_excel_writer::PolarsXlsxWriter to write the Polars dataframe to the worksheet.
• 2b: rust_xlsxwriter to add other features to the worksheet.

This may seem initially complicated but it divides the solution into specialized libraries that are best suited for their task and it allow you to access advanced Excel functionality that isn’t provided by PolarsXlsxWriter.

One aspect to note in this example is the transparent handling of the different error types. That is explained in the next section.

PolarsError and XlsxError

The rust_xlsxwriter crate uses an error type called XlsxError while Polars and PolarsXlsxWriter use an error type called [PolarsError]. In order to make interoperability with Polars easier the rust_xlsxwriter::XlsxError type maps to (and from) the PolarsError type.

That is why in the previous example we were able to use two different error types within the same result/error context of PolarsError. Note, the error type is not explicit in the previous example but PolarsResult<T> expands to Result<T, PolarsError>.

In order for this to be enabled you must use the rust_xlsxwriter polars crate feature, however, this is turned on automatically when you use polars_excel_writer.

Implementations

impl PolarsXlsxWriter

pub fn new() -> PolarsXlsxWriter

Create a new PolarsXlsxWriter instance.

pub fn write_dataframe(&mut self, df: &DataFrame) -> PolarsResult<()>

Write a dataframe to a worksheet.

Writes the supplied dataframe to cell (0, 0) in the first sheet of a new Excel workbook.

The worksheet must be written to a file using save().

Parameters

• df - A Polars dataframe.

Errors

A [PolarsError::ComputeError] that wraps a rust_xlsxwriter XlsxError error.

Examples

An example of writing a Polar Rust dataframe to an Excel file.

use polars_excel_writer::PolarsXlsxWriter;

fn main() -> PolarsResult<()> {
    let df: DataFrame = df!(
        "Data" => &[10, 20, 15, 25, 30, 20],
    )?;

    // Write the dataframe to an Excel file.
    let mut xlsx_writer = PolarsXlsxWriter::new();

    xlsx_writer.write_dataframe(&df)?;
    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

pub fn write_dataframe_to_cell( &mut self, df: &DataFrame, row: u32, col: u16 ) -> PolarsResult<()>

Write a dataframe to a user defined cell in a worksheet.

Writes the supplied dataframe to a user defined cell in the first sheet of a new Excel workbook.

Since the dataframe can be positioned within the worksheet it is possible to write more than one to the same worksheet (without overlapping).

The worksheet must be written to a file using save().

Parameters

• df - A Polars dataframe.
• row - The zero indexed row number.
• col - The zero indexed column number.

Errors

A [PolarsError::ComputeError] that wraps a rust_xlsxwriter XlsxError error.

Examples

An example of writing more than one Polar dataframes to an Excel worksheet.

use polars_excel_writer::PolarsXlsxWriter;

fn main() -> PolarsResult<()> {
    let df1: DataFrame = df!(
        "Data 1" => &[10, 20, 15, 25, 30, 20],
    )?;

    let df2: DataFrame = df!(
        "Data 2" => &[1.23, 2.34, 3.56],
    )?;

    // Write the dataframe to an Excel file.
    let mut xlsx_writer = PolarsXlsxWriter::new();

    // Write two dataframes to the same worksheet.
    xlsx_writer.write_dataframe_to_cell(&df1, 0, 0)?;
    xlsx_writer.write_dataframe_to_cell(&df2, 0, 2)?;

    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

pub fn write_dataframe_to_worksheet( &mut self, df: &DataFrame, worksheet: &mut Worksheet, row: u32, col: u16 ) -> PolarsResult<()>

Write a dataframe to a user supplied worksheet.

Writes the dataframe to a rust_xlsxwriter Worksheet object. This worksheet cannot be saved via save(). Instead it must be used in conjunction with a rust_xlsxwriter Workbook.

This is useful for mixing PolarsXlsxWriter data writing with additional Excel functionality provided by rust_xlsxwriter. See Interacting with rust_xlsxwriter and the example below.

Parameters

• df - A Polars dataframe.
• worksheet - A rust_xlsxwriter Worksheet.
• row - The zero indexed row number.
• col - The zero indexed column number.

Errors

A [PolarsError::ComputeError] that wraps a rust_xlsxwriter XlsxError error.

Examples

An example of using polars_excel_writer in conjunction with rust_xlsxwriter to write a Polars dataframe to a worksheet and then add a chart to plot the data.

use polars_excel_writer::PolarsXlsxWriter;
use rust_xlsxwriter::{Chart, ChartType, Workbook};

fn main() -> PolarsResult<()> {
    // Create a sample dataframe using `Polars`
    let df: DataFrame = df!(
        "Data" => &[10, 20, 15, 25, 30, 20],
    )?;

    // Get some dataframe dimensions that we will use for the chart range.
    let row_min = 1; // Skip the header row.
    let row_max = df.height() as u32;

    // Create a new workbook and worksheet using `rust_xlsxwriter`.
    let mut workbook = Workbook::new();
    let worksheet = workbook.add_worksheet();

    // Write the dataframe to the worksheet using `PolarsXlsxWriter`.
    let mut xlsx_writer = PolarsXlsxWriter::new();
    xlsx_writer.write_dataframe_to_worksheet(&df, worksheet, 0, 0)?;

    // Move back to `rust_xlsxwriter` to create a new chart and have it plot the
    // range of the dataframe in the worksheet.
    let mut chart = Chart::new(ChartType::Line);
    chart
        .add_series()
        .set_values(("Sheet1", row_min, 0, row_max, 0));

    // Add the chart to the worksheet.
    worksheet.insert_chart(0, 2, &chart)?;

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

    Ok(())
}

Output file:

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

Save the Workbook as an xlsx file.

The save() method writes all the workbook and worksheet data to a new xlsx file. It will overwrite any existing file.

The method can be called multiple times so it is possible to get incremental files at different stages of a process, or to save the same Workbook object to different paths. However, save() is an expensive operation which assembles multiple files into an xlsx/zip container so for performance reasons you shouldn’t call it unnecessarily.

Parameters

• path - The path of the new Excel file to create as a &str or as a std::path Path or PathBuf instance.

Errors

A [PolarsError::ComputeError] that wraps a rust_xlsxwriter XlsxError error.

pub fn set_header(&mut self, has_header: bool) -> &mut PolarsXlsxWriter

Turn on/off the dataframe header in the exported Excel file.

Turn on/off the dataframe header row in the Excel table. It is on by default.

Parameters

• has_header - Export dataframe with/without header.

Examples

An example of writing a Polar Rust dataframe to an Excel file. This demonstrates saving the dataframe without a header.

use polars_excel_writer::PolarsXlsxWriter;

fn example(df: &DataFrame) -> PolarsResult<()> {
    let mut xlsx_writer = PolarsXlsxWriter::new();

    xlsx_writer.set_header(false);

    xlsx_writer.write_dataframe(df)?;
    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

pub fn set_time_format( &mut self, format: impl Into<Format> ) -> &mut PolarsXlsxWriter

Set the Excel number format for time values.

Datetimes in Excel are stored as f64 floats with a format used to display them. The default time format used by this library is hh:mm:ss;@. This method can be used to specify an alternative user defined format.

Parameters

• format - A rust_xlsxwriter Format or an Excel number format string that can be converted to a Format.

Examples

An example of writing a Polar Rust dataframe to an Excel file. This example demonstrates how to change the default format for Polars time types.

use chrono::prelude::*;
use polars::prelude::*;

fn main() {
    // Create a sample dataframe for the example.
    let df: DataFrame = df!(
        "Time" => &[
            NaiveTime::from_hms_milli_opt(2, 00, 3, 456).unwrap(),
            NaiveTime::from_hms_milli_opt(2, 18, 3, 456).unwrap(),
            NaiveTime::from_hms_milli_opt(2, 37, 3, 456).unwrap(),
            NaiveTime::from_hms_milli_opt(2, 59, 3, 456).unwrap(),
        ],
    )
    .unwrap();

    example(&df).unwrap();
}

use polars_excel_writer::PolarsXlsxWriter;

fn example(df: &DataFrame) -> PolarsResult<()> {
    let mut xlsx_writer = PolarsXlsxWriter::new();

    xlsx_writer.set_time_format("hh:mm");

    xlsx_writer.write_dataframe(df)?;
    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

pub fn set_date_format( &mut self, format: impl Into<Format> ) -> &mut PolarsXlsxWriter

Set the Excel number format for date values.

Datetimes in Excel are stored as f64 floats with a format used to display them. The default date format used by this library is yyyy-mm-dd;@. This method can be used to specify an alternative user defined format.

Parameters

• format - A rust_xlsxwriter Format or an Excel number format string that can be converted to a Format.

Examples

An example of writing a Polar Rust dataframe to an Excel file. This example demonstrates how to change the default format for Polars date types.

use chrono::prelude::*;
use polars::prelude::*;

fn main() {
    // Create a sample dataframe for the example.
    let df: DataFrame = df!(
        "Date" => &[
            NaiveDate::from_ymd_opt(2023, 1, 11),
            NaiveDate::from_ymd_opt(2023, 1, 12),
            NaiveDate::from_ymd_opt(2023, 1, 13),
            NaiveDate::from_ymd_opt(2023, 1, 14),
        ],
    )
    .unwrap();

    example(&df).unwrap();
}

use polars_excel_writer::PolarsXlsxWriter;

fn example(df: &DataFrame) -> PolarsResult<()> {
    let mut xlsx_writer = PolarsXlsxWriter::new();

    xlsx_writer.set_date_format("mmm d yyyy");

    xlsx_writer.write_dataframe(df)?;
    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

pub fn set_datetime_format( &mut self, format: impl Into<Format> ) -> &mut PolarsXlsxWriter

Set the Excel number format for datetime values.

Datetimes in Excel are stored as f64 floats with a format used to display them. The default datetime format used by this library is yyyy-mm-dd hh:mm:ss. This method can be used to specify an alternative user defined format.

Parameters

• format - A rust_xlsxwriter Format or an Excel number format string that can be converted to a Format.

Examples

An example of writing a Polar Rust dataframe to an Excel file. This example demonstrates how to change the default format for Polars datetime types.

use chrono::prelude::*;
use polars::prelude::*;

fn main() {
    // Create a sample dataframe for the example.
    let df: DataFrame = df!(
        "Datetime" => &[
            NaiveDate::from_ymd_opt(2023, 1, 11).unwrap().and_hms_opt(1, 0, 0).unwrap(),
            NaiveDate::from_ymd_opt(2023, 1, 12).unwrap().and_hms_opt(2, 0, 0).unwrap(),
            NaiveDate::from_ymd_opt(2023, 1, 13).unwrap().and_hms_opt(3, 0, 0).unwrap(),
            NaiveDate::from_ymd_opt(2023, 1, 14).unwrap().and_hms_opt(4, 0, 0).unwrap(),
        ],
    )
    .unwrap();

    example(&df).unwrap();
}

use polars_excel_writer::PolarsXlsxWriter;

fn example(df: &DataFrame) -> PolarsResult<()> {
    let mut xlsx_writer = PolarsXlsxWriter::new();

    xlsx_writer.set_datetime_format("hh::mm - mmm d yyyy");

    xlsx_writer.write_dataframe(df)?;
    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

pub fn set_float_format( &mut self, format: impl Into<Format> ) -> &mut PolarsXlsxWriter

Set the Excel number format for floats.

Set the Excel number format for f32/f64 float types using an Excel number format string. These format strings can be obtained from the Format Cells -> Number dialog in Excel.

See the Number Format Categories section and subsequent Number Format sections in the rust_xlsxwriter documentation.

Note, the numeric values aren’t truncated in Excel, this option just controls the display of the number.

Parameters

• format - A rust_xlsxwriter Format or an Excel number format string that can be converted to a Format.

Examples

An example of writing a Polar Rust dataframe to an Excel file. This demonstrates setting an Excel number format for floats.

use polars::prelude::*;

fn main() {
    // Create a sample dataframe for the example.
    let df: DataFrame = df!(
        "Float" => &[1000.0, 2000.22, 3000.333, 4000.4444],
    )
    .unwrap();

    example(&df).unwrap();
}

use polars_excel_writer::PolarsXlsxWriter;

fn example(df: &DataFrame) -> PolarsResult<()> {
    let mut xlsx_writer = PolarsXlsxWriter::new();

    xlsx_writer.set_float_format("#,##0.00");

    xlsx_writer.write_dataframe(df)?;
    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

pub fn set_float_precision(&mut self, precision: usize) -> &mut PolarsXlsxWriter

Set the Excel number precision for floats.

Set the number precision of all floats exported from the dataframe to Excel. The precision is converted to an Excel number format (see set_float_format() above), so for example 3 is converted to the Excel format 0.000.

Note, the numeric values aren’t truncated in Excel, this option just controls the display of the number.

Parameters

• precision - The floating point precision in the Excel range 1-30.

Examples

An example of writing a Polar Rust dataframe to an Excel file. This example demonstrates how to set the precision of the float output. Setting the precision to 3 is equivalent to an Excel number format of 0.000.

use polars::prelude::*;

fn main() {
    // Create a sample dataframe for the example.
    let df: DataFrame = df!(
        "Float" => &[1.0, 2.22, 3.333, 4.4444],
    )
    .unwrap();

    example(&df).unwrap();
}

use polars_excel_writer::PolarsXlsxWriter;

fn example(df: &DataFrame) -> PolarsResult<()> {
    let mut xlsx_writer = PolarsXlsxWriter::new();

    xlsx_writer.set_float_precision(3);

    xlsx_writer.write_dataframe(df)?;
    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

pub fn set_null_value( &mut self, null_value: impl Into<String> ) -> &mut PolarsXlsxWriter

Replace Null values in the exported dataframe with string values.

By default Null values in a dataframe aren’t exported to Excel and will appear as empty cells. If you wish you can specify a string such as “Null”, “NULL” or “N/A” as an alternative.

Parameters

• null_value - A replacement string for Null values.

Examples

An example of writing a Polar Rust dataframe to an Excel file. This demonstrates setting a value for Null values in the dataframe. The default is to write them as blank cells.

use polars_excel_writer::PolarsXlsxWriter;

fn example(df: &DataFrame) -> PolarsResult<()> {
    let mut xlsx_writer = PolarsXlsxWriter::new();

    xlsx_writer.set_null_value("Null");

    xlsx_writer.write_dataframe(df)?;
    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

pub fn set_autofit(&mut self, autofit: bool) -> &mut PolarsXlsxWriter

Simulate autofit for columns in the dataframe output.

Use a simulated autofit to adjust dataframe columns to the maximum string or number widths.

Note: There are several limitations to this autofit method, see the rust_xlsxwriter docs on worksheet.autofit() for details.

Parameters

• autofit - Turn autofit on/off. It is off by default.

Examples

An example of writing a Polar Rust dataframe to an Excel file. This example demonstrates autofitting column widths in the output worksheet.

use polars::prelude::*;

fn main() {
    // Create a sample dataframe for the example.
    let df: DataFrame = df!(
        "Col 1" => &["A", "B", "C", "D"],
        "Column 2" => &["A", "B", "C", "D"],
        "Column 3" => &["Hello", "World", "Hello, world", "Ciao"],
        "Column 4" => &[1234567, 12345678, 123456789, 1234567],
    )
    .unwrap();

    example(&df).unwrap();
}

use polars_excel_writer::PolarsXlsxWriter;

fn example(df: &DataFrame) -> PolarsResult<()> {
    let mut xlsx_writer = PolarsXlsxWriter::new();

    xlsx_writer.set_autofit(true);

    xlsx_writer.write_dataframe(df)?;
    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

pub fn set_table(&mut self, table: &Table) -> &mut PolarsXlsxWriter

Set the worksheet table for the output dataframe.

By default, and by convention with the Polars write_excel() method, PolarsXlsxWriter adds an Excel worksheet table to each exported dataframe.

Tables in Excel are a way of grouping a range of cells into a single entity that has common formatting or that can be referenced from formulas. Tables can have column headers, autofilters, total rows, column formulas and different formatting styles.

The image below shows a default table in Excel with the default properties shown in the ribbon bar.

The set_table() method allows you to pass a pre-configured rust_xlsxwriter table and override any of the default Table properties.

Parameters

• table - A rust_xlsxwriter Table reference.

Examples

An example of writing a Polar Rust dataframe to an Excel file. This demonstrates setting properties of the worksheet table that wraps the output dataframe.

use polars_excel_writer::PolarsXlsxWriter;
use rust_xlsxwriter::*;

fn example(df: &DataFrame) -> PolarsResult<()> {
    let mut xlsx_writer = PolarsXlsxWriter::new();

    // Add a `rust_xlsxwriter` table and set the style.
    let table = Table::new().set_style(TableStyle::Medium4);

    // Add the table to the Excel writer.
    xlsx_writer.set_table(&table);

    xlsx_writer.write_dataframe(df)?;
    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

pub fn set_worksheet_name( &mut self, name: impl Into<String> ) -> PolarsResult<&mut PolarsXlsxWriter>

Set the worksheet name for the output dataframe.

Set the name of the worksheet that the dataframe is written to. If the name isn’t set then it will be the default Excel name of Sheet1 (or Sheet2, Sheet3, etc. if more than one worksheet is added).

Parameters

• name - The worksheet name. It must follow the Excel rules, shown below.

  • The name must be less than 32 characters.
  • The name cannot be blank.
  • The name cannot contain any of the characters: [ ] : * ? / \.
  • The name cannot start or end with an apostrophe.
  • The name shouldn’t be “History” (case-insensitive) since that is reserved by Excel.
  • It must not be a duplicate of another worksheet name used in the workbook.

Errors

A [PolarsError::ComputeError] that wraps a rust_xlsxwriter XlsxError error.

Excel has several rules that govern what a worksheet name can be. See set_name() errors for more details.

Examples

An example of writing a Polar Rust dataframe to an Excel file. This demonstrates setting the name for the output worksheet.

use polars_excel_writer::PolarsXlsxWriter;

fn example(df: &DataFrame) -> PolarsResult<()> {
    let mut xlsx_writer = PolarsXlsxWriter::new();

    xlsx_writer.set_worksheet_name("Polars Data")?;

    xlsx_writer.write_dataframe(df)?;
    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

pub fn add_worksheet(&mut self) -> &mut PolarsXlsxWriter

Add a new worksheet to the output workbook.

Add a worksheet to the workbook so that dataframes can be written to more than one worksheet. This is useful when you have several dataframes that you wish to have on separate worksheets.

Examples

An example of writing a Polar Rust dataframes to separate worksheets in an Excel workbook.

use polars_excel_writer::PolarsXlsxWriter;

fn main() -> PolarsResult<()> {
    let df1: DataFrame = df!(
        "Data 1" => &[10, 11, 12, 13, 14, 15],
    )?;

    let df2: DataFrame = df!(
        "Data 2" => &[20, 21, 22, 23, 24, 25],
    )?;

    let mut xlsx_writer = PolarsXlsxWriter::new();

    // Write the first dataframe to the first/default worksheet.
    xlsx_writer.write_dataframe(&df1)?;

    // Add another worksheet and write the second dataframe to it.
    xlsx_writer.add_worksheet();
    xlsx_writer.write_dataframe(&df2)?;

    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

pub fn worksheet(&mut self) -> PolarsResult<&mut Worksheet>

Get the current worksheet in the workbook.

Get a reference to the current/last worksheet in the workbook in order to manipulate it with a rust_xlsxwriter Worksheet method. This is occasionally useful when you need to access some feature of the worksheet APIs that isn’t supported directly by PolarsXlsxWriter.

Note, it is also possible to create a Worksheet separately and then write the Polar dataframe to it using the write_dataframe_to_worksheet() method. That latter is more useful if you need to do a lot of manipulation of the worksheet.

Errors

A [PolarsError::ComputeError] that wraps a rust_xlsxwriter XlsxError error.

Examples

An example of writing a Polar Rust dataframe to an Excel file. This demonstrates getting a reference to the worksheet used to write the dataframe and setting its tab color.

use polars_excel_writer::PolarsXlsxWriter;

fn example(df: &DataFrame) -> PolarsResult<()> {
    let mut xlsx_writer = PolarsXlsxWriter::new();

    // Get the worksheet that the dataframe will be written to.
    let worksheet = xlsx_writer.worksheet()?;

    // Set the tab color for the worksheet using a `rust_xlsxwriter` worksheet
    // method.
    worksheet.set_tab_color("#FF9900");

    xlsx_writer.write_dataframe(df)?;
    xlsx_writer.save("dataframe.xlsx")?;

    Ok(())
}

Output file:

Trait Implementations

impl Default for PolarsXlsxWriter

fn default() -> Self

Returns the “default value” for a type.