xlswrite

Syntax

 xlswrite(filename,A)
 xlswrite(filename,A,sheet)
 xlswrite(filename,A,xlRange)
 xlswrite(filename,A,sheet,xlRange)
 status = xlswrite(___)
 [status,message] = xlswrite(___)

Description

xlswrite(filename,A) writes matrix A to the first worksheet in the

Microsoft® Excel® spreadsheet workbook filename starting at cell
A1.xlswrite(filename,A,sheet) writes to the specified worksheet.
xlswrite(filename,A,xlRange) writes to the rectangular region specified
by xlRange in the first worksheet of the workbook. Use Excel range syntax, such
as 'A1:C3'.

xlswrite(filename,A,sheet,xlRange) writes to the specified

worksheet and range.

status = xlswrite(___) returns the status of the write operation, using

any of the input arguments in previous syntaxes. When the operation is successful,
status is 1. Otherwise, status is 0.

[status,message] = xlswrite(___) additionally returns any warning

or error message generated by the write operation in structure message.

Examples

Write Vector to Spreadsheet

Write a 7-element vector to an Excel® file.

filename = 'testdata.xlsx';
A = [12.7 5.02 -98 63.9 0 -.2 56];
xlswrite(filename,A)
Write to Specific Sheet and Range in Spreadsheet

Write mixed text and numeric data to an Excel® file starting at cell E1 of
Sheet2.

filename = 'testdata.xlsx';
A = {'Time','Temperature'; 12,98; 13,99; 14,97};
sheet = 2;
xlRange = 'E1';
xlswrite(filename,A,sheet,xlRange)

Input Arguments

filename — File name

character vector

File name, specified as a character vector.

If filename does not exist, xlswrite creates a file, determining the format
based on the specified extension. To create a file compatible with Excel 97-2003
software, specify an extension of .xls. To create files in Excel 2007 formats,
specify an extension of .xlsx, .xlsb, or .xlsm. If you do not specify an
extension, xlswrite uses the default, .xls.

Example: 'myFile.xlsx'

Example: 'C:\myFolder\myFile.xlsx'

A — Input matrix
matrix

Input matrix, specified as a two-dimensional numeric or character array, or, if each

cell contains a single element, a cell array.

If A is a cell array containing something other than a scalar numeric or text, then
xlswrite silently leaves the corresponding cell in the spreadsheet empty.

The maximum size of array A depends on the associated Excel version. For more
information on Excel specifications and limits, see the Excel help.
Example: [10,2,45;-32,478,50]

Example: {92.0,'Yes',45.9,'No'}

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 |

uint16 | uint32 | uint64 | logical | char | cell

sheet — Worksheet name character vector | positive integer

Worksheet name, specified as one of the following:

 Character vector that contains the worksheet name. The name cannot contain
a colon (:). To determine the names of the sheets in a spreadsheet file, use
xlsfinfo.
 Positive integer that indicates the worksheet index.

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.

xlRange — Rectangular range character vector

Rectangular range, specified as a character vector.

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

 If you do not specify sheet, then xlRange must include both corners and
a colon character, even for a single cell (such as 'D2:D2'). Otherwise,
xlswrite interprets the input as a worksheet name (such as 'D2').
 If you specify sheet, then xlRange can specify only the first cell (such as
'D2'). xlswrite writes input array A beginning at this cell.
  If xlRange is larger than the size of input array A, Excel software fills the
remainder of the region with #N/A. If xlRange is smaller than the size of
A, then xlswrite writes only the subset that fits into xlRange to the file.

Output Arguments

status — Status of the write operation

1|0

Status of the write operation, returned as either 1 (true) or 0 (false). When the
write operation is successful, status is 1. Otherwise, status is 0.

message — Error or warning generated during the write operation

structure array

Limitations

 If your computer does not have Excel for Windows®, or if the COM server
(part of the typical installation of Excel) is unavailable, then the xlswrite
function:
o Writes array A to a text file in comma-separated value (CSV) format.
A must be a numeric matrix.
o Ignores the sheet and xlRange arguments.

More About

Tips

 If your computer has Microsoft Office 2003 software, but you want to create
a file in an Excel 2007 format, install the Office 2007 Compatibility Pack.
 Excel and MATLAB® can store dates as text that represents those dates
(such as '10/31/96') or serial date numbers (such as 729329). If your
array includes serial date numbers, convert these dates to their text
representation using datestr before calling xlswrite. Alternatively,
see Import and Export Dates to Excel Files.
 To write data to Excel files with custom formats (such as fonts or colors),
access the Windows COM server directly using actxserver rather than
xlswrite. For example, this MathWorks Support Answer uses
actxserver to establish a connection between MATLAB and Excel,
writes data to a worksheet, and specifies the colors of the cells.
xlsread
Read Microsoft Excel spreadsheet file

Syntax

 num = xlsread(filename)
 num = xlsread(filename,sheet)
 num = xlsread(filename,xlRange)
 num = xlsread(filename,sheet,xlRange)
 num = xlsread(filename,sheet,xlRange,'basic')
 [num,txt,raw] = xlsread(___)

 ___ = xlsread(filename,-1)

 [num,txt,raw,custom] =
xlsread(filename,sheet,xlRange,'',processFcn)

Description

num = xlsread(filename) reads the first worksheet in the Microsoft®

Excel® spreadsheet workbook named filename and returns the numeric data in a
matrix.

num = xlsread(filename,sheet) reads the specified worksheet.

num = xlsread(filename,xlRange) reads from the specified range of

the first worksheet in the workbook. Use Excel range syntax, such as 'A1:C3'.

num = xlsread(filename,sheet,xlRange) reads from the specified

worksheet and range.

num = xlsread(filename,sheet,xlRange,'basic') reads data

from the spreadsheet in basic import mode. If your computer does not have
Excel for Windows®, xlsread automatically operates in basic import mode,
which supports XLS, XLSX, XLSM, XLTX, and XLTM files.

If you do not specify all the arguments, use empty character vectors, '' , as
placeholders, for example, num = xlsread(filename,'','','basic').
[num,txt,raw] = xlsread(___) additionally returns the text fields in cell
array txt, and both numeric and text data in cell array raw, using any of the input
arguments in the previous syntaxes.

___ = xlsread(filename,-1) opens an Excel window to interactively

select data. Select the worksheet, drag and drop the mouse over the range you
want, and click OK. This syntax is supported only on Windows computers with
Microsoft Excel software installed.

[num,txt,raw,custom] =
xlsread(filename,sheet,xlRange,'',processFcn), where
processFcn is a function handle, reads from the spreadsheet, calls
processFcn on the data, and returns the final results as numeric data in array
num. The xlsread function returns the text fields in cell array txt, both the
numeric and text data in cell array raw, and the second output from processFcn
in array custom. The xlsread function does not change the data stored in the
spreadsheet. This syntax is supported only on Windows computers with Excel
software.

Examples

Read Worksheet Into Numeric Matrix

Create an Excel file named myExample.xlsx.

values = {1, 2, 3 ; 4, 5, 'x' ; 7, 8, 9};

headers = {'First','Second','Third'};
xlswrite('myExample.xlsx',[headers; values]);

Sheet1 of myExample.xlsx contains:

First Second Third

1 2 3
4 5 x
7 8 9
Read numeric data from the first worksheet.

filename = 'myExample.xlsx';
A = xlsread(filename)
A =
1 2 3
4 5 NaN
7 8 9

Read Range of Cells

Read a specific range of data from the Excel file in the previous example.

filename = 'myExample.xlsx';
sheet = 1;
xlRange = 'B2:C3';

subsetA = xlsread(filename,sheet,xlRange)
subsetA =
2 3
5 NaN

Read Column

Read the second column from the Excel file in the first example.

filename = 'myExample.xlsx';

columnB = xlsread(filename,'B:B')
columnB =
2
5
8

For better performance, include the row numbers in the range, such as 'B1:B3'.

Request Numeric, Text, and Raw Data

Request the numeric data, text data, and combined data from the Excel file in the
first example.
[num,txt,raw] = xlsread('myExample.xlsx')
num =
1 2 3
4 5 NaN
7 8 9

txt =
'First' 'Second' 'Third'
'' '' ''
'' '' 'x'

raw =
'First' 'Second' 'Third'
[ 1] [ 2] [ 3]
[ 4] [ 5] 'x'
[ 7] [ 8] [ 9]

Execute a Function on a Worksheet

In the Editor, create a function to process data from a worksheet. In this case, set
values outside the range [0.2,0.8] to 0.2 or 0.8.

function [Data] = setMinMax(Data)

minval = 0.2;
maxval = 0.8;

for k = 1:Data.Count
v = Data.Value{k};
if v > maxval
Data.Value{k} = maxval;
elseif v < minval
Data.Value{k} = minval;
end
end

In the Command Window, add random data to myExample.xlsx.

A = rand(5);
xlswrite('myExample.xlsx',A,'MyData')
The worksheet named MyData contains values ranging from 0 to 1.

Read the data from the worksheet, and reset any values outside the range
[0.2,0.8]. Specify the sheet name, but use '' as placeholders for the
xlRange and 'basic' inputs.

trim =
xlsread('myExample.xlsx','MyData','','',@setMinMax);

Request Custom Output

Execute a function on a worksheet and display the custom index output.

In the Editor, modify the function setMinMax from the previous example to
return the indices of the changed elements (custom output).

function [Data,indices] = setMinMax(Data)

minval = 0.2;
maxval = 0.8;
indices = [];

for k = 1:Data.Count
v = Data.Value{k};
if v > maxval
Data.Value{k} = maxval;
indices = [indices k];
elseif v < minval
Data.Value{k} = minval;
indices = [indices k];
end
end

Read the data from the worksheet MyData, and request the custom index output,
idx.

[trim,txt,raw,idx] = xlsread('myExample.xlsx',...
'MyData','','',@setMinMax);
Input Arguments

filename — File name character vector

File name, specified as a character vector. If you do not include an extension,

xlsread searches for a file with the specified name and a supported Excel
extension. xlsread can read data saved in files that are currently open in Excel
for Windows.

Example: 'myFile.xlsx'

Data Types: char

sheet — Worksheet character vector | positive integer

Worksheet, specified as one of the following:

 Character vector that contains the worksheet name. The name cannot contain
a colon (:). To determine the names of the sheets in a spreadsheet file, use
xlsfinfo. For XLS files in basic mode, sheet is case sensitive.
 Positive integer that indicates the worksheet index. This option is not
supported for XLS files in basic mode.

xlRange — Rectangular range character vector

Rectangular range, specified as a character vector.

Specify xlRange using two opposing corners that define the region to read. For
example, 'D2:H4' represents the 3-by-5 rectangular region between the two
corners D2 and H4 on the worksheet. The xlRange input is not case sensitive,
and uses Excel A1 reference style (see Excel help).

Range selection is not supported when reading XLS files in basic mode. In this
case, use '' in place of xlRange.

If you do not specify sheet, then xlRange must include both corners and a
colon character, even for a single cell (such as 'D2:D2'). Otherwise, xlsread
interprets the input as a worksheet name (such as 'sales' or 'D2').

If you specify sheet, then xlRange:

  Does not need to include a colon and opposite corner to describe a single
cell.
 Can refer to a named range that you defined in the Excel file (see the Excel
help).

When the specified xlRange overlaps merged cells:

 On Windows computers with Excel, xlsread expands the range to include

all merged cells.
 On computers without Excel for Windows, xlsread returns data for the
specified range only, with empty or NaN values for merged cells.

Data Types: char

'basic' — Flag to request reading in basic mode character vector

Flag to request reading in basic mode, specified as the character vector,

'basic'.

basic mode is the default for computers without Excel for Windows. In basic
mode, xlsread:

 Reads XLS, XLSX, XLSM, XLTX, and XLTM files only.

 Does not support an xlRange input when reading XLS files. In this case,
use '' in place of xlRange.
 Does not support function handle inputs.
 Imports all dates as Excel serial date numbers. Excel serial date numbers use
a different reference date than MATLAB® date numbers.

processFcn — Handle to a custom function function handle

Handle to a custom function. This argument is supported only on Windows

computers with Excel software. xlsread reads from the spreadsheet, executes
your function on a copy of the data, and returns the final results. xlsread does
not change the data stored in the spreadsheet.

When xlsread calls the custom function, it passes a range interface from the
Excel application to provide access to the data. The custom function must include
this interface both as an input and output argument. (See Execute a Function on a
Worksheet)
Example: @myFunction

Output Arguments

num — Numeric data matrix

Numeric data, returned as a matrix of double values. The array does not contain
any information from header lines, or from outer rows or columns that contain
nonnumeric data. Text data in inner spreadsheet rows and columns appear as NaN
in the num output.

txt — Text data cell array

Text data, returned as a cell array. Numeric values in inner spreadsheet rows and
columns appear as empty character vectors, '', in txt.

For XLS files in basic import mode, the txt output contains empty character
vectors, '', in place of leading columns of numeric data that precede text data in
the spreadsheet. In all other cases, txt does not contain these additional columns.

Undefined values (such as '#N/A') appear in the txt output as '#N/A', except
for XLS files in basic mode.

raw — Numeric and text data cell array

Numeric and text data from the worksheet, returned as a cell array.

On computers with Excel for Windows, undefined values (such as '#N/A')

appear in the raw output as 'ActiveX VT_ERROR:'. For XLSX, XLSM,
XLTX, and XLTM files on other computers, undefined values appear as '#N/A'.

custom — Second output of the function corresponding to processFcn

defined by the function