xlsxWrite

Arguments

data

A double matrix, string matrix, or cell containing the data to write.

filename

A string specifying the path to the Excel (.xlsx) file to write.

"sheet", sheet_value

A string (sheet name) or positive integer (sheet index, 1-based) specifying which sheet to write to.

• If string: the sheet name must already exist. Writes to existing sheet with that name.

• If integer: the sheet at that index must already exist, otherwise an error occurs.

Default: 1 (first sheet). Optional.

"range", range_value

A string or 2x2 matrix specifying where to start writing data.

String formats: "A1:C10" (cell range), "A:C" (column range), "1:3" (row range), "B5" (first cell), "B" (first column), "3" (first row).

Matrix format: [row1 col1; row2 col2] where all values are positive integers >= 1.

Default: "". Optional.

"writemode", writemode_value

A string specifying the write mode:

• "overwrite": Clears the sheet before writing data.

• "append": Keeps existing data and adds new data at the specified range.

Default: data is written without clearing (preserves other cells). Optional.

"title", title_value

A string specifying the document title metadata embedded in Excel file properties. Optional.

"subject", subject_value

A string specifying the document subject metadata embedded in Excel file properties. Optional.

"description", description_value

A string specifying the document description metadata embedded in Excel file properties. Optional.

Description

Write data to an Excel (.xlsx) file. Accepts matrices or cells. To write table and timeseries to an Excel file, use readtable and readtimeseries functions.

The function uses key-value pairs to specify options. All parameters except data and filename are optional and can be combined in any order.

File and sheet handling:

• If the file exists, data is written to the specified sheet.

• Sheet names (strings) must reference existing sheets, otherwise an error occurs.

• Sheet indices (integers) must reference existing sheets, otherwise an error occurs.

Data types:

• Matrix: Values are written in Excel.

• cell: Heterogen values are written in Excel.

Range specification:

Ranges can be specified as strings (Excel notation "A1:B6") or as a 2x2 scilab matrix [start_row start_col; end_row end_col].

The range defines the starting position for writing.

Write modes:

• Default (no writemode): Writes data at specified range, preserving other cells in the sheet.

• "overwrite": Clears entire sheet before writing.

• "append": Explicitly preserves existing data, writes at specified range.

Metadata:

Title, subject, and description options set Excel document properties (visible in File > Properties in Excel).

Return values

This function does not return a value. It writes the data to the specified Excel file.

If an error occurs during writing, an error message is raised with details about the failure.

Potential errors:

• Invalid parameters: Wrong argument types or invalid option keys

• Data type error: Data must be double matrix, string matrix, or cell

• Sheet index error: Specified sheet index doesn't exist in file

• Range format error: Invalid range specification

• File access error: Insufficient permissions, disk full, or file locked by another process

• XLNT library error: Excel format or compatibility issues

Examples

// Create example data
data = [1 2 3; 4 5 6; 7 8 9];
test_file = TMPDIR + "/test_write.xlsx";

// Write numeric matrix to default sheet starting at A1
xlsxWrite(data, test_file);

// Write to specific sheet by name
xlsxWrite(data, test_file, "sheet", "Sheet1");

// Write to specific sheet by index (must exist)
xlsxWrite(data, test_file, "sheet", 1);

// Write starting at specific position
xlsxWrite(data, test_file, "range", "B5");

// Write using matrix range notation [row col]
xlsxWrite(data, test_file, "range", [5 2; 13 4]);  // B5:D13

// Clear sheet before writing (overwrite mode)
xlsxWrite(data, test_file, "sheet", 1, "writemode", "overwrite");

// Append data preserving existing content
xlsxWrite(data, test_file, "sheet", 1, "writemode", "append", "range", "A10");

// Write with document metadata
xlsxWrite(data, test_file, "title", "My Report", "subject", "Data Analysis", ..
          "description", "Quarterly analysis results");

// Write string matrix
text_data = ["Name" "Age" "City"; "Alice" "25" "Paris"; "Bob" "30" "London"];
people_file = TMPDIR + "/people.xlsx";
xlsxWrite(text_data, people_file, "sheet", 1);

// Write cell
c = {1, "A"; 2, "B"; 3, "C"}
cell_file = TMPDIR + "/cell_data.xlsx";
xlsxWrite(c, cell_file);

// Complete example combining all options
report_file = TMPDIR + "/report.xlsx";
xlsxWrite(data, report_file, "sheet", 1, "range", "B2", ..
          "writemode", "overwrite", "title", "Q1 Report", ..
          "subject", "Sales Data", "description", "First quarter sales figures");

ret = xlsxRead(report_file)

See also

• xlsxRead — Read data from an Excel file and return a matrix or cell.
• xlsxSheet — Manage sheets in an Excel file.
• xlsxInfo — Get information about an Excel file.

History