readcell
Create cell array from file
Syntax
Description
C = readcell(
creates a cell array by
reading column-oriented data from a text or spreadsheet file.filename
)
C = readcell(
specifies options using one or more name-value arguments. For example, you can specify the
number of header lines in the file, the expected number of variables or columns, or a range
of data to read.filename
,Name,Value
)
C = readcell(
creates a cell array using the options specified by the import options object
filename
,opts
)opts
. Use an import options object to configure how
readcell
interprets your file. Compared to the previous two syntaxes,
an import options object provides more control, better performance, and reusability of the
file import configuration.
C = readcell(
creates a cell array using both an import options object and name-value arguments. If you
specify name-value arguments in addition to an import options object, then
filename
,opts
,Name,Value
)readcell
supports only the DateLocale
and
Encoding
name-value arguments for text files, and the
Sheet
and UseExcel
name-value arguments for
spreadsheet files.
Examples
Read from Text File
Import the contents of a text file into a cell array. readcell
imports each element of the text file as a cell in the output cell array.
C = readcell("basic_cell.txt")
C=3×3 cell array
{[ 1]} {[ 2]} {[ 3]}
{'hello' } {'world'} {[ NaN]}
{[10-Oct-2018 10:27:56]} {[ 1]} {[<missing>]}
Read from Spreadsheet
Import tabular data from a spreadsheet file into a cell array.
C = readcell("basic_cell.xls")
C=3×3 cell array
{[ 1]} {[ 2]} {[ 3]}
{'hello' } {'world'} {[<missing>]}
{[10-Oct-2018 10:27:56]} {[ 1]} {[<missing>]}
Read Specific Range from Spreadsheet
Import data from a specified sheet and range into a cell array.
The airlinesmall_subset.xlsx
spreadsheet file contains data in multiple worksheets for years between 1996 and 2008. Each sheet in the spreadsheet file has data for a given year.
Import 10 rows of data from columns G, H, and I from the sheet named "2007
". The Excel® range "G2:I11
" represents the region of data defined by columns G through I and rows 2 to 11 (the first 10 rows after the header row).
C = readcell("airlinesmall_subset.xlsx","Sheet","2007","Range","G2:I11")
C=10×3 cell array
{[ 935]} {[ 935]} {'WN'}
{[1041]} {[1040]} {'WN'}
{[1430]} {[1500]} {'WN'}
{[ 940]} {[ 950]} {'WN'}
{[1515]} {[1515]} {'WN'}
{[2042]} {[2035]} {'WN'}
{[2116]} {[2130]} {'WN'}
{[1604]} {[1605]} {'WN'}
{[1258]} {[1230]} {'WN'}
{[1134]} {[1145]} {'WN'}
Detect and Use Import Options for Text File
Import a subset of variables from a text file using an import options object.
Use the detectImportOptions
function to detect aspects of your text file, including the variable names and types, delimiters, and white-space characters. The import options object opts
stores the detected file aspects as properties.
opts = detectImportOptions("airlinesmall.csv")
opts = DelimitedTextImportOptions with properties: Format Properties: Delimiter: {','} Whitespace: '\b\t ' LineEnding: {'\n' '\r' '\r\n'} CommentStyle: {} ConsecutiveDelimitersRule: 'split' LeadingDelimitersRule: 'keep' TrailingDelimitersRule: 'ignore' EmptyLineRule: 'skip' Encoding: 'ISO-8859-1' Replacement Properties: MissingRule: 'fill' ImportErrorRule: 'fill' ExtraColumnsRule: 'addvars' Variable Import Properties: Set types by name using setvartype VariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more} VariableTypes: {'double', 'double', 'double' ... and 26 more} SelectedVariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more} VariableOptions: [1-by-29 matlab.io.VariableImportOptions] Access VariableOptions sub-properties using setvaropts/getvaropts VariableNamingRule: 'modify' Location Properties: DataLines: [2 Inf] VariableNamesLine: 1 RowNamesColumn: 0 VariableUnitsLine: 0 VariableDescriptionsLine: 0 To display a preview of the table, use preview
Specify the subset of variables to import and the end-of-line character by modifying the import options object.
opts.SelectedVariableNames = ["Year","Month","DayofMonth"]; opts.LineEnding = "\n";
Import the subset of data using readcell
with the import options object.
C = readcell("airlinesmall.csv",opts);
Input Arguments
filename
— Name of file to read
string scalar | character vector
Name of the file to read, specified as a string scalar or character vector. You can specify one of these file formats:
Delimited text file or fixed-width text file with a
.txt
,.dat
, or.csv
extension.For delimited text files and fixed-width text files,
readcell
converts empty fields tomissing
values.All lines in the text file must have the same number of delimiters.
readcell
ignores insignificant white space in the file.
Spreadsheet file with a
.xls
,.xlsb
,.xlsm
,.xlsx
,.xltm
,.xltx
, or.ods
extension.On Windows® systems with Microsoft® Excel®,
readcell
reads any Excel spreadsheet file format recognized by your version of Excel.If your system does not have Excel for Windows or if you are using MATLAB® Online™,
readcell
reads only.xls
,.xlsm
,.xlsx
,.xltm
, and.xltx
files.
If filename
does not include an extension, use the
FileType
name-value argument to indicate the file format.
Depending on the location of your file, filename
can take on one
of these forms.
Location | Form | ||||||||
---|---|---|---|---|---|---|---|---|---|
Current folder or folder on the MATLAB path | Specify the name of the file in
Example:
| ||||||||
File in a folder | If the file is not in the current folder or in a folder on the
MATLAB path, then specify the full or relative pathname in
Example:
Example:
| ||||||||
Internet URL | If the file is specified as an internet uniform resource locator
(URL), then Example:
| ||||||||
Remote location | If the file is stored at a remote location, then
Based on the remote location,
For more information, see Work with Remote Data. Example:
|
opts
— File import options
DelimitedTextImportOptions
object | FixedWidthImportOptions
object | SpreadsheetImportOptions
object
File import options, specified as one of the import options objects in the table,
created by either the detectImportOptions
function or the
associated import options function. The import options object contains properties that
configure the data import process. The table shows the properties of each import options
object that readcell
applies when importing data.
File Type | Import Options Object | Applied Properties |
---|---|---|
Delimited text files | DelimitedTextImportOptions object |
|
Fixed-width text files | FixedWidthImportOptions object |
|
Spreadsheet files |
|
|
For more information on how to control your import, see Control How MATLAB Imports Your Data.
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Example: readcell(filename,NumHeaderLines=5)
indicates that the first
five lines of the specified file are header lines.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: readcell(filename,"NumHeaderLines",5)
indicates that the first
five lines of the specified file are header lines.
FileType
— Type of file
"text"
| "spreadsheet"
Type of file, specified as "text"
or
"spreadsheet"
.
Specify the FileType
name-value argument when
filename
does not include the file extension or if the extension
is one other than:
.txt
,.dat
, or.csv
for delimited or fixed-width text files.xls
,.xlsb
,.xlsm
,.xlsx
,.xltm
,.xltx
, or.ods
for spreadsheet files
Example: "FileType","text"
Delimiter
— Field delimiter characters
string array | character vector | cell array of character vectors
Field delimiter characters in a delimited text file, specified as a string array, character vector, or cell array of character vectors.
Example: "Delimiter","|"
Example: "Delimiter",[";","*"]
LeadingDelimitersRule
— Procedure to manage leading delimiters
"keep"
| "ignore"
| "error"
Procedure to manage leading delimiters in a delimited text file, specified as one of the values in this table.
Value | Behavior |
---|---|
"keep" | Keep the delimiter. |
"ignore" | Ignore the delimiter. |
"error" | Return an error and cancel the import operation. |
TrailingDelimitersRule
— Procedure to manage trailing delimiters
"keep"
| "ignore"
| "error"
Procedure to manage trailing delimiters in a delimited text file, specified as one of the values in this table.
Value | Behavior |
---|---|
"keep" | Keep the delimiter. |
"ignore" | Ignore the delimiter. |
"error" | Return an error and cancel the import operation. |
ConsecutiveDelimitersRule
— Procedure to manage consecutive delimiters
"split"
| "join"
| "error"
Procedure to manage consecutive delimiters in a delimited text file, specified as one of the values in this table.
Value | Behavior |
---|---|
"split" | Split the consecutive delimiters into multiple fields. |
"join" | Join the delimiters into one delimiter. |
"error" | Return an error and cancel the import operation. |
NumHeaderLines
— Number of header lines
positive integer
Number of header lines in the file, specified as a positive integer. If
unspecified, readcell
automatically detects the number of header
lines in the file.
Example: "NumHeaderLines",7
TextType
— Type for imported text data
"string"
| "char"
Type for imported text data, specified as one of these values:
"string"
— Import text data as string arrays."char"
— Import text data as character vectors.
Example: "TextType","char"
DatetimeType
— Type for imported date and time data
"datetime"
(default) | "text"
Type for imported date and time data, specified as one of the values in this table.
Value | Description |
---|---|
"datetime" | MATLAB
For more information,
see |
"text" | The type for imported date and time data depends on the value
specified in the
|
ExpectedNumVariables
— Expected number of variables or columns
positive integer
Expected number of variables or columns, specified as a positive integer. If
unspecified, readcell
automatically detects the number of variables
or columns.
Range
— Portion of data to read
string scalar | character vector | numeric vector
Portion of the data to read from text files, specified as a string scalar, character vector, or numeric vector in one of these forms.
Ways to Specify Range | Description |
---|---|
Starting cell
| Specify the starting cell for the data:
Using the starting cell, Example:
|
Rectangular range
| Specify the exact region to read using a rectangular range in one of these forms:
|
Row range or column range
| Specify the range by identifying the beginning and ending rows using Excel row numbers. Using the specified row range,
Example:
Alternatively, specify the range by identifying the beginning and ending columns using Excel column letters or numbers. Using the specified
column range, The number of columns in the specified range must
match the number specified in the Example:
|
Starting row number
| Specify the first row containing the data using the positive scalar row index. Using the specified row index,
Example:
|
Excel’s named range
| In Excel, you can create names to identify ranges in a spreadsheet. For
instance, you can select a rectangular portion of the spreadsheet and name
it Example:
|
Unspecified or empty
| If unspecified or empty, Example:
Note:
Used range refers to the rectangular portion of the
spreadsheet that actually contains data. |
WebOptions
— HTTP
or HTTPS
request options
weboptions
object
HTTP
or HTTPS
request options, specified as
a weboptions
object. The
weboptions
object determines how to import data when the
specified filename
is an internet URL containing the protocol type
"http://"
or "https://"
.
Whitespace
— Characters to treat as white space
character vector | string scalar
Characters to treat as white space, specified as a character vector or string scalar containing one or more characters.
Example: 'Whitespace',' _'
Example: 'Whitespace','?!.,'
LineEnding
— End-of-line characters
["\n","\r","\r\n"]
(default) | string array | character vector | cell array of character vectors
End-of-line characters, specified as a string array, character vector, or cell array of character vectors.
Example: "LineEnding","\n"
Example: "LineEnding","\r\n"
Example: "LineEnding",["\b",":"]
CommentStyle
— Style of comments
string array | character vector | cell array of character vectors
Style of comments, specified as a string array, character vector, or cell array of character vectors. For single- and multi-line comments, the starting identifier must be the first non-white-space character. For single-line comments, specify a single identifier to treat lines starting with the identifier as comments. For multi-line comments, lines from the starting (first) identifier to the ending (second) identifier are treated as comments. No more than two character vectors of identifiers can be specified.
For example, to ignore the line following a percent symbol as the first
non-white-space character, specify CommentStyle
as
"%"
.
Example: "CommentStyle",["/*"]
Example: "CommentStyle",["/*","*/"]
Encoding
— Character encoding scheme
"system"
| "UTF-8"
| "ISO-8859-1"
| "windows-1251"
| "windows-1252"
| ...
Character encoding scheme associated with the file, specified as
"system"
or a standard character encoding scheme name. When you
do not specify any encoding, readcell
uses automatic character
set detection to determine the encoding when reading the file.
If you specify the Encoding
argument in addition to an import
options object, then readcell
uses the specified value for
Encoding
, overriding the encoding defined in the import
options.
Example: "Encoding","UTF-8"
uses UTF-8 as the
encoding.
Example: "Encoding","system"
uses the system default
encoding.
DurationType
— Output data type of duration data
"duration"
(default) | "text"
Output data type of duration data from text files, specified as one of the values in this table.
Value | Type for Imported Duration Data |
---|---|
"duration" | The MATLAB
For more information,
see |
"text" | The type for imported duration data depends on the value
specified in the
|
DateLocale
— Locale for reading dates
string scalar | character vector
Locale for reading dates, specified as a string scalar or a character vector of
the form
, where:xx
_YY
xx
is a lowercase ISO 639-1 two-letter code indicating a language.YY
is an uppercase ISO 3166-1 alpha-2 code indicating a country.
This table lists some common values for the locale.
Locale | Language | Country |
---|---|---|
"de_DE" | German | Germany |
"en_GB" | English | United Kingdom |
"en_US" | English | United States |
"es_ES" | Spanish | Spain |
"fr_FR" | French | France |
"it_IT" | Italian | Italy |
"ja_JP" | Japanese | Japan |
"ko_KR" | Korean | Korea |
"nl_NL" | Dutch | Netherlands |
"zh_CN" | Chinese (simplified) | China |
When using the %D
format specifier to read text as
datetime
values, use DateLocale
to specify the
locale in which readcell
should interpret month and day-of-week
names and abbreviations.
If you specify the DateLocale
argument in addition to an import
options object, then readcell
uses the specified value for the
DateLocale
argument, overriding the locale defined in the import
options.
Example: "DateLocale","ja_JP"
FileType
— Type of file
"text"
| "spreadsheet"
Type of file, specified as "text"
or
"spreadsheet"
.
Specify the FileType
name-value pair argument when the
filename
does not include the file extension or if the extension
is one other than:
.txt
,.dat
, or.csv
for delimited or fixed-width text files.xls
,.xlsb
,.xlsm
,.xlsx
,.xltm
,.xltx
, or.ods
for spreadsheet files
Example: "FileType","text"
NumHeaderLines
— Number of header lines
positive integer
Number of header lines in the file, specified as a positive integer. If
unspecified, readcell
automatically detects the number of header
lines in the file.
Example: "NumHeaderLines",7
TextType
— Type for imported text data
"string"
| "char"
Type for imported text data, specified as one of these values:
"string"
— Import text data as string arrays."char"
— Import text data as character vectors.
Example: "TextType","char"
DatetimeType
— Type for imported date and time data
"datetime"
(default) | "text"
| "exceldatenum"
(spreadsheet files only)
Type for imported date and time data, specified as one of the values in this table.
Value | Description |
---|---|
"datetime" | MATLAB
For more information,
see |
"text" | The type for imported date and time data depends on the value
specified in the
|
"exceldatenum"
| Excel serial date numbers The value
|
ExpectedNumVariables
— Expected number of variables or columns
positive integer
Expected number of variables or columns, specified as a positive integer. If
unspecified, readcell
automatically detects the number of variables
or columns.
Sheet
— Sheet to read from
''
empty character array (default) | character vector | string scalar | positive integer scalar
Sheet to read from, specified as an empty character array, a character vector or
string scalar containing the sheet name, or a positive integer scalar denoting the
sheet index. Based on the value specified for the Sheet
name-value
argument, readcell
behaves as described in the table.
Specification | Behavior |
---|---|
'' (default) | Import data from the first sheet. |
Sheet name | Import data from the matching sheet name, regardless of the order of sheets in the spreadsheet file. |
Sheet index | Import data from the sheet in the position denoted by the index, regardless of the sheet names in the spreadsheet file. |
Range
— Portion of data to read
string scalar | character vector | numeric vector
Portion of the data to read from spreadsheet files, specified as a string scalar, character vector, or numeric vector in one of these forms.
Ways to Specify Range | Description |
---|---|
Starting cell
| Specify the starting cell for the data as:
Using the starting cell, Example:
|
Rectangular range
| Specify the exact region to read using a rectangular range in one of these forms:
|
Row range or column range
| Specify the range by identifying the beginning and ending rows using Excel row numbers. Using the specified row range,
Example:
Alternatively, specify the range by identifying the beginning and ending columns using Excel column letters or numbers. Using the specified
column range, The number of columns in the specified range must
match the number specified in the Example:
|
Starting row number
| Specify the first row containing the data using the positive scalar row index. Using the specified row index,
Example:
|
Excel’s named range
| In Excel, you can create names to identify ranges in a spreadsheet. For
instance, you can select a rectangular portion of the spreadsheet and name
it Example:
|
Unspecified or empty
| If unspecified or empty, Example:
Note:
Used range refers to the rectangular portion of the
spreadsheet that actually contains data. |
DurationType
— Output data type of duration data
"duration"
(default) | "text"
Output data type of duration data from spreadsheet files, specified as one of the values in this table.
Value | Type for Imported Duration Data |
---|---|
"duration" | The MATLAB
For more information,
see |
"text" | The type for imported duration data depends on the value
specified in the
|
WebOptions
— HTTP
or HTTPS
request options
weboptions
object
HTTP
or HTTPS
request options, specified as
a weboptions
object. The
weboptions
object determines how to import data when the
specified filename
is an internet URL containing the protocol type
"http://"
or "https://"
.
UseExcel
— Flag to start instance of Microsoft Excel for Windows
false
or 0
(default) | true
or 1
Flag to start an instance of Microsoft Excel for Windows when reading spreadsheet data, specified as one of these values:
1
(true
) — Start an instance of Microsoft Excel when reading the file.0 (
false
) — Do not start an instance of Microsoft Excel when reading the file. When operating in this mode,readcell
functionality differs in the support of file formats and interactive features, such as formulas and macros.
UseExcel |
|
|
---|---|---|
Supported file formats |
|
|
Support for interactive features, such as formulas and macros | Yes | No |
UseExcel
is not supported in noninteractive, automated
environments.
MergedCellColumnRule
— Rule for cells merged across columns
"placeleft"
(default) | "placeright"
| "duplicate"
| "omitrow"
| "error"
Since R2024b
Rule for cells merged across columns, specified as one of the values in this table.
Import Rule | Behavior |
---|---|
"placeleft" | Place the data in the leftmost cell and fill the remaining cells
with the contents of the You can specify the |
"placeright" | Place the data in the rightmost cell and fill the remaining cells
with the contents of the You can specify the |
"duplicate" | Duplicate the data in all cells. |
"omitrow" | Omit rows where merged cells occur. |
"error" | Display an error message and cancel the import operation. |
MergedCellRowRule
— Rule for cells merged across rows
"placetop"
(default) | "placebottom"
| "duplicate"
| "omitvar"
| "error"
Since R2024b
Rule for cells merged across rows, specified as one of the values in this table.
Import Rule | Behavior |
---|---|
"placetop" | Place the data in the top cell and fill the remaining cells with
the contents of the You
can specify the |
"placebottom" | Place the data in the bottom cell and fill the remaining cells
with the contents of the You can specify the |
"duplicate" | Duplicate the data in all cells. |
"omitvar" | Omit variables where merged cells occur. |
"error" | Display an error message and cancel the import operation. |
Version History
Introduced in R2019aR2024b: Specify how to import merged cells in spreadsheets
When importing data from spreadsheets, you can specify how readcell
imports cells that are merged across rows and columns by using the
MergedCellRowRule
and MergedCellColumnRule
name-value arguments.
See Also
readtable
| readtimetable
| readmatrix
| readvars
| writecell
Comando de MATLAB
Ha hecho clic en un enlace que corresponde a este comando de MATLAB:
Ejecute el comando introduciéndolo en la ventana de comandos de MATLAB. Los navegadores web no admiten comandos de MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)