Navigation

Operators and Keywords

Function List:

C++ API

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] = xlsread (filename, wsh, range, reqintf)

Read data contained in range range from worksheet wsh in Excel spreadsheet file filename. 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, etc.).

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

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. the leftmost worksheet in the Excel 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.

The optional last argument reqintf 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 (OpenOffice.org), or native Octave (only reading .xlsx) (in that -built in- order of preference). For reading from OOXML 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.

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 (1/1/1900 & 1/1/0000, resp.). Spreadsheet date values lying before 1/1/1900 are returned as strings, formatted as they appear in the spreadsheet. 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.

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.

Examples:

             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