xlsxRead

Arguments

filename

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

"sheet", sheet_value

A string (sheet name) or positive integer (sheet index) specifying which sheet to read. Default: first sheet. Optional.

"range", range_value

A string or 2x2 matrix specifying the range of cells to read.

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. Optional.

"conversion", conversion_type

A string specifying the output data type:

• "double" (default): Returns a numeric matrix. Datetime values are converted to datenum, non-numeric values become NaN.

• "string": Returns a string matrix. All values (including datetimes) are converted to strings.

• "cell": Returns a cell.

Description

Read data from an Excel (.xlsx) file and return it in the requested format (double matrix, string matrix, or cell).

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

Conversion modes:

• "double" (default): Returns a numeric matrix. Numeric values are preserved, and non-numeric values become NaN.

• "string": Returns a string matrix. All values are converted to strings.

• "cell": Returns a cell.

Range specification:

Ranges can be specified as strings (Excel notation) or as a 2x2 matrix [start_row start_col; end_row end_col] with 1-based indexing.

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

Datetime handling:

Datetime values in Excel cells are converted.

• In "double" mode: converted to datenum

• In "string" mode: converted to string

• In "cell" mode: converted to datetime

To read a table or timeseries, use readtable and readtimeseries functions.

Examples

// Create example data file
data = [1, 2, 3; 4, 5, 6; 7, 8, 9];
test_file = TMPDIR + "/test_read.xlsx";
xlsxWrite(data, test_file);

// Read entire first sheet as double matrix
data = xlsxRead(test_file)
// [1 2 3
// 4 5 6
// 7 8 9]

// Read specific sheet by name
data = xlsxRead(test_file, "sheet", "Sheet1")
// [1 2 3
// 4 5 6
// 7 8 9]

// Read specific sheet by index (1-based)
data = xlsxRead(test_file, "sheet", 1);

// Read specific range from first sheet
data = xlsxRead(test_file, "range", "A1:C10")
// [1 2 3
// 4 5 6
// 7 8 9]

// Read rows 7 to 8 from first sheet
data = xlsxRead(test_file, "range", "1:8")
// [1 2 3
// 4 5 6
// 7 8 9]

// Read columns A to C
data = xlsxRead(test_file, "range", "A:C")
// [1 2 3
// 4 5 6
// 7 8 9]

// Read specific range using matrix notation [row col]
data = xlsxRead(test_file, "range", [1 1; 10 3])  // A1:C10

// Read specific range from specific sheet
data = xlsxRead(test_file, "sheet", "Sheet1", "range", "B2:D5")
// [5 6
// 8 9]

// Read as string matrix instead of double
data = xlsxRead(test_file, "range", "A1:B5", "conversion", "string")
// ["1" "2"
// "4" "5"
// "7" "8"]

// Read as cell
data = xlsxRead(test_file, "conversion", "cell")
// {1 2 3
// 4 5 6
// 7 8 9}

See also

• xlsxWrite — Write data (matrix or cell) to an Excel file.
• xlsxSheet — Manage sheets in an Excel file.
• xlsxInfo — Get information about an Excel file.

History