Function File: [ numarr , txtarr, rawarr, limits] = xlsread (filename)
Function File: [ numarr , txtarr, rawarr, limits] = xlsread (filename, wsh)
Function File: [ numarr , txtarr, rawarr, limits] = xlsread (filename, range)
Function File: [ numarr , txtarr, rawarr, limits] = xlsread (filename, wsh, range)
Function File: [ numarr , txtarr, rawarr, limits, extout] = xlsread (filename, wsh, range, options, …)

Read data contained in range range from worksheet wsh in Excel spreadsheet file filename. Gnumeric files can also be read.

Return argument numarr contains the numeric data, optional return arguments txtarr and rawarr contain text strings and the raw spreadsheet cell data, respectively. Return argument limits contains the outer column/row numbers of the read spreadsheet range where numarr, txtarr and rawarr have come from (remember, xlsread trims outer rows and columns).

If filename does not contain any directory, the file is assumed to be in the current directory. The filename extension (.xls or .xlsx) must be included in the file name; when using the COM interface all file formats can be read that are supported by the locally installed MS-Excel version (e.g., wk1, csv, dbf, .xlsm, etc.). The same holds for UNO ( or LibreOffice).

range is expected to be a regular spreadsheet range format, or "" (empty string, indicating all data in a worksheet). If no range is specified the occupied cell range will have to be determined behind the scenes first; this can take some time for the Java-based interfaces (but the results may be more reliable than that of ActiveX/COM). Instead of a spreadsheet range a Named range defined in the spreadsheet file can be used as well. In that case the Named range should be specified as 3rd argument and the value of 2nd argument wsh doesn’t matter as the worksheet associated with the specified Named range will be used.

wsh is either numerical or text; in the latter case it is case-sensitive and it may be max. 31 characters long. Note that in case of a numerical wsh this number refers to the position in the worksheet stack, counted from the left in an Excel window. The default is numerical 1, i.e. corresponding to the leftmost worksheet tab in the spreadsheet file.

If only the first argument is specified, xlsread will try to read all contents (as if a range of ’' (empty string) was specified) from the first = leftmost (or the only) worksheet

If only two arguments are specified, xlsread assumes the second argument to be range if it is a string argument and contains a ":" or if it is ’' (empty string), and in those cases assumes the data must be read from the first worksheet (not necessarily Sheet1! but the leftmost sheet).

However, if only two arguments are specified and the second argument is numeric or a text string that does not contain a ":", it is assumed to be wsh and to refer to a worksheet. In that case xlsread tries to read all data contained in that worksheet.

To be able to use Named ranges, the second input argument should refer to a worksheet and the third should be the Named range.

After these input arguments a number of optional arguments can be supplied in any desired order:


Interface (a three-character text sting) can be used to override the automatic interface selection by xlsread out of the supported ones: COM/Excel, Java/Apache POI, Java/JExcelAPI, Java/OpenXLS, Java/UNO (, or native Octave (in that -built in- order of preference). For I/O to/from .xlsx files a value of ’com’, ’poi’, ’uno’, or ’oct’ must be specified for reqintf (see help for xlsopen). For Excel’95 files use ’com’, or if Excel is not installed use ’jxl’, ’basic’ or ’uno’. POI can’t read Excel’95 but will try to fall back to JXL. As reqintf can also be a cell array of strings, one can select or exclude one or more interfaces. In addition the OCT interface offers .gnumeric read support.

Function handle

If a function handle is specified, the pertinent function (having at most two output arrays) will be applied to the numeric output data of xlsread. Any second output of the function will be in a 5th output argument extout of xlsread.

Options struct

xlsread’s output can be influenced to some extent by a number of options. See OPTIONS in "help xls2oct" for an overview.

Erroneous data and empty cells are set to NaN in numarr and turn up empty in txtarr and rawarr. Date/time values in Excel are returned as numerical values in numarr. Note that Excel and Octave have different date base values (epoch; 1/1/1900 & 1/1/0000, resp.). When using the COM interface, spreadsheet date values lying before 1/1/1900 are returned as strings, formatted as they appear in the spreadsheet. The returned date format for other interfaces depend on interface type and support SW version. numarr and txtarr are trimmed from empty outer rows and columns. Be aware that Excel does the same for rawarr, so any returned array may turn out to be smaller than requested in range. Use the fourth return argument LIMS for info on the cell ranges your date came from.

When reading from merged cells, all array elements NOT corresponding to the leftmost or upper Excel cell will be treated as if the "corresponding" Excel cells are empty.

xlsread is just a wrapper for a collection of scripts that find out the interface to be used (COM, Java/POI, Java/JXL Java/OXS, Java/UNO, OCT) and do the actual reading. For each call to xlsread the interface must be started and the Excel file read into memory. When reading multiple ranges (in optionally multiple worksheets) a significant speed boost can be obtained by invoking those scripts directly as in: xlsopen / xls2oct [/ parsecell] / ... / xlsclose

Beware: when using the COM interface, hidden Excel invocations may be kept running silently if not closed explicitly.


  A = xlsread ('test4.xls', '2nd_sheet', 'C3:AB40');
  (which returns the numeric contents in range C3:AB40 in worksheet
  '2nd_sheet' from file test4.xls into numeric array A) 
  [An, Tn, Ra, limits] = xlsread ('Sales2009.xls', 'Third_sheet');
  (which returns all data in worksheet 'Third_sheet' in file 'Sales2009.xls'
  into array An, the text data into array Tn, the raw cell data into
  cell array Ra and the ranges from where the actual data came in limits)
  numarr = xlsread ('Sales2010.xls', 4, [], {'JXL', 'COM'});
  (Read all data from 4th worksheet in file Sales2010.xls using either JXL
   or COM interface (i.e, exclude POI interface). 

See also: xlswrite, xlsopen, xls2oct, xlsclose, xlsfinfo, oct2xls.

Package: io