Xlswrite - Write Microsoft Excel Spreadsheet File

MATLAB® /
Provide feedback about this page

xlswrite - Write Microsoft Excel spreadsheet file

Syntax

xlswrite(filename, M)
xlswrite(filename, M, sheet)
xlswrite(filename, M, range)
xlswrite(filename, M, sheet, range)
status = xlswrite(filename, ...)
[status, message] = xlswrite(filename, ...)
xlswrite filename M sheet range

Description

xlswrite(filename, M) writes matrix M to the Excel file filename. The filename input is a string enclosed in single quotation marks, and should include the file extension. The matrix M is an m-by-n numeric or character array. xlswrite writes the matrix data to the first worksheet in the file, starting at cell A1.

The matrix M can also be an m-by-n cell array if each cell includes a single element (see Example 2). To write cell arrays containing more than one element in each cell, use low-level export functions.

If filename does not exist, xlswrite creates a new file. The file extension you provide as part of filename determines the Excel format that xlswrite uses for the new file. An extension of .xls creates a worksheet compatible with Excel 97-2003 software. Use extensions .xlsx, .xlsb, or .xlsm to create worksheets in Excel 2007 file formats. The maximum size of the matrix M depends on the associated Excel version. (For more information on Excel specifications and limits, see Excel help.)

xlswrite(filename, M, sheet) writes matrix M to the specified worksheet sheet in the file filename. The sheet argument can be either a positive, double scalar value representing the worksheet index, or a quoted string containing the sheet name. The sheet argument cannot contain a colon.

If sheet does not exist, xlswrite adds a new sheet at the end of the worksheet collection. If sheet is an index larger than the number of worksheets, xlswrite appends empty sheets until the number of worksheets in the workbook equals sheet. In either case, xlswrite generates a warning indicating that it has added a new worksheet.

xlswrite(filename, M, range) writes matrix M to a rectangular region specified by range in the first worksheet of the file filename.

Specify range using the syntax 'C1:C2', where C1 and C2 are two opposing corners that define the region to write. For example, the range 'D2:H4' represents the 3-by-5 rectangular region between the two corners D2 and H4 on the worksheet. The range input is not case sensitive and uses the Excel A1 reference style. (For more information on this reference style, see Excel help.) xlswrite does not recognize named ranges.

The size defined by range should fit the size of M. If range is larger than the size of M, Excel software fills the remainder of the region with #N/A. If range is smaller than the size of M, xlswrite writes only the submatrix that fits into range to the file specified by filename.

Note If you specify only three inputs, xlswrite must decide whether the third input refers to a sheet or a range. To specify a range, include a colon character in the input string (such as 'D2:H4'). If you do not include a colon character (such as 'sales' or 'D2'), xlswrite interprets the third input as a value for sheet.

xlswrite(filename, M, sheet, range) writes matrix M to a rectangular region specified by range in worksheet sheet of the file filename. If you specify both sheet and range, the range can either fit the size of M or contain only the first cell (such as 'A2'). See the previous two syntax formats for further explanation of the sheet and range inputs.

status = xlswrite(filename, ...) returns the completion status of the write operation in status. If the write completes successfully, status is equal to logical 1 (true). Otherwise, status is logical 0 (false). Unless you specify an output parameter, xlswrite does not display a status value in the Command Window.

[status, message] = xlswrite(filename, ...) returns any warning or error message generated by the write operation in the MATLAB structure message. The message structure has two fields:

message — String containing the text of the warning or error message
identifier — String containing the message identifier for the warning or error

xlswrite filename M sheet range is the command format for xlswrite, showing its usage with all input arguments specified. When using this format, you must specify sheet as a string (for example, Income or Sheet4). If the sheet name contains space characters, then you must place quotation marks around the string (for example, 'Income 2002').

Remarks

Full functionality of xlswrite depends on the use of the Microsoft Excel COM server. The typical installation of Excel for Windows includes access to this server. If your system does not have Excel for Windows installed, or if the COM server is unavailable, xlswrite:

Writes matrix M as a text file in comma-separated value (CSV) format.
Ignores the sheet and range arguments.
Generates an error if the input matrix M is a cell array.

If your system has Microsoft Office 2003 software installed, but you want to create a file in an Excel 2007 format, you must install the Office 2007 Compatibility Pack.

Both Excel and MATLAB applications represent numeric dates as a number of serial days elapsed from a specific reference date. However, Excel and MATLAB use different reference dates:

Application / Reference Date /
MATLAB / January 0, 0000
Excel for Windows / January 1, 1900
Excel for the Macintosh / January 2, 1904

For more information, see Converting Dates in the MATLAB Programming Fundamentals documentation.

Examples

Example 1 — Writing Numeric Data to the Default Worksheet

Write a 7-element vector to Microsoft Excel file testdata.xls. By default, xlswrite writes the data to cells A1 through G1 in the first worksheet in the file:

xlswrite('testdata.xls', [12.7 5.02 -98 63.9 0 -.2 56])

Example 2 — Writing Mixed Data to a Specific Worksheet

This example writes the following mixed text and numeric data to the file tempdata.xls:

d = {'Time', 'Temp'; 12 98; 13 99; 14 97};

Call xlswrite, specifying the worksheet labeled Temperatures, and the region within the worksheet to write the data to. xlswrite writes the 4-by-2 matrix to the rectangular region that starts at cell E1 in its upper left corner:

s = xlswrite('tempdata.xls', d, 'Temperatures', 'E1')

s =

The output status s shows that the write operation succeeded. The data appears as shown here in the output file:

Time Temp

12 98

13 99

14 97

Example 3 — Appending a New Worksheet to the File

Now write the same data to a worksheet that doesn't yet exist in tempdata.xls. In this case, xlswrite appends a new sheet to the workbook, calling it by the name you supplied in the sheets input argument, 'NewTemp'. xlswrite displays a warning indicating that it has added a new worksheet to the file:

xlswrite('tempdata.xls', d, 'NewTemp', 'E1')

Warning: Added specified worksheet.

If you don't want to see these warnings, you can turn them off with this command:

warning off MATLAB:xlswrite:AddSheet

Now try the write command again, this time creating another new worksheet, NewTemp2. Although the message does not appear this time, you can still retrieve it and its identifier from the second output argument, msg:

[stat msg] = xlswrite('tempdata.xls', d, 'NewTemp2', 'E1');

msg

msg =

message: 'Added specified worksheet.'

identifier: 'MATLAB:xlswrite:AddSheet'