Main Content

readcell

基于文件创建元胞数组

自 R2019a 起

说明

示例

C = readcell(filename) 通过从文本文件或电子表格文件中读取列向数据来创建元胞数组。

示例

C = readcell(filename,Name,Value) 使用一个或多个名称-值参量指定选项。例如,您可以指定文件中标题行的行数、预期的变量数或列数,或要读取的数据范围。

示例

C = readcell(filename,opts) 使用导入选项对象 opts 指定的选项创建元胞数组。使用导入选项对象来配置 readcell 解读文件的方式。与前两种语法相比,导入选项对象在文件导入配置上可以提供更多的控制、更好的性能,并可重复使用

C = readcell(filename,opts,Name,Value) 使用导入选项对象和名称-值参量创建元胞数组。如果除了导入选项对象之外还指定名称-值参量,则 readcell 对文本文件仅支持 DateLocaleEncoding 名称-值参量,对电子表格文件仅支持 SheetUseExcel 名称-值参量。

示例

全部折叠

将文本文件的内容导入元胞数组。readcell 将文本文件的每个元素以元胞形式导入输出元胞数组。

C = readcell("basic_cell.txt")
C=3×3 cell array
    {[                   1]}    {[    2]}    {[        3]}
    {'hello'               }    {'world'}    {[      NaN]}
    {[10-Oct-2018 10:27:56]}    {[    1]}    {[<missing>]}

将表格数据从电子表格文件导入元胞数组。

C = readcell("basic_cell.xls")
C=3×3 cell array
    {[                   1]}    {[    2]}    {[        3]}
    {'hello'               }    {'world'}    {[<missing>]}
    {[10-Oct-2018 10:27:56]}    {[    1]}    {[<missing>]}

将指定的工作表和范围中的数据导入元胞数组。

电子表格文件 airlinesmall_subset.xlsx 包含 1996 年至 2008 年间多个工作表中的数据。电子表格文件中的每个工作表都包含一个给定年份的数据。

从名为 "2007" 的工作表的 G、H 和 I 列导入 10 行数据。Excel® 范围 "G2:I11" 表示由 G 列到 I 列以及第 2 行到第 11 行(标题行后的前 10 行)所定义的数据区域。

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'}

使用导入选项对象从文本文件导入变量的子集。

使用 detectImportOptions 函数检测文本文件的各个方面,包括变量名称和类型、分隔符以及空白字符。导入选项对象 opts 将检测到的文件各方面的数据存储为属性。

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

通过修改导入选项对象,指定要导入的变量子集和行尾字符。

opts.SelectedVariableNames = ["Year","Month","DayofMonth"];
opts.LineEnding = "\n";

通过将 readcell 与导入选项对象配合使用,导入数据子集。

C = readcell("airlinesmall.csv",opts);

输入参数

全部折叠

要读取的文件的名称,指定为字符串标量或字符向量。您可以指定以下文件格式之一:

  • 扩展名为 .txt.dat.csv 的带分隔符的文本文件或等宽文本文件。

    • 对于带分隔符的文本文件和等宽文本文件,readcell 将空字段转换为 missing 值。

    • 文本文件中的所有行必须有相同数量的分隔符。

    • readcell 会忽略文件中的无用空白。

  • 扩展名为 .xls.xlsb.xlsm.xlsx.xltm.xltx.ods 的电子表格文件。

    • 在安装了 Microsoft® Excel® 的 Windows® 系统上,readcell 能够读取您的 Excel 版本可识别的任何 Excel 电子表格文件格式。

    • 如果您的系统没有 Windows 版的 Excel,或您正在使用 MATLAB® Online™,则 readcell 只能读取 .xls.xlsm.xlsx.xltm.xltx 文件。

如果 filename 不包含扩展名,请使用 FileType 名称-值参量来指示文件格式。

根据文件的位置,filename 可以采用下列形式之一。

位置

形式

当前文件夹或 MATLAB 路径上的文件夹

指定 filename 中文件的名称。

例如:"myFile.txt"

文件夹中的文件

如果该文件不在当前文件夹或 MATLAB 路径下的文件夹中,则在 filename 中指定完整或相对路径名称。

例如:"C:\myFolder\myFile.xlsx"

例如:"dataDir\myFile.txt"

Internet URL

如果文件指定为 Internet 统一资源定位器 (URL),则 filename 必须包含协议类型 "http://""https://"

例如:"http://hostname/path_to_file/my_data.csv"

远程位置

如果文件存储在远程位置,则 filename 必须包含用以下格式指定的文件的完整路径:

scheme_name://path_to_file/my_file.ext

根据远程位置,scheme_name 可以是下表中的值之一。

远程位置scheme_name
Amazon S3™s3
Windows Azure® Blob 存储wasb, wasbs
HDFS™hdfs

有关详细信息,请参阅处理远程数据

例如: "s3://bucketname/path_to_file/my_file.csv"

文件导入选项,指定为表中的导入选项对象之一,由 detectImportOptions 函数或关联的导入选项函数创建。导入选项对象包含用于配置数据导入过程的属性。下表显示 readcell 在导入数据时应用的每个导入选项对象的属性。

文件类型导入选项对象应用的属性
带分隔符的文本文件DelimitedTextImportOptions 对象
  • SelectedVariableNames

  • DataLines

  • Delimiter

  • Whitespace

  • LineEnding

  • CommentStyle

  • ConsecutiveDelimitersRule

  • LeadingDelimitersRule

  • TrailingDelimitersRule

  • Encoding

  • MissingRule

  • EmptyLineRule

  • ExtraColumnsRule

等宽文本文件FixedWidthImportOptions 对象
  • SelectedVariableNames

  • DataLines

  • VariableWidths

  • Whitespace

  • LineEnding

  • CommentStyle

  • Encoding

  • PartialFieldRule

  • EmptyLineRule

  • MissingRule

  • ExtraColumnsRule

电子表格文件

SpreadsheetImportOptions 对象

  • SelectedVariableNames

  • Sheet

  • DataRange

  • MissingRule

  • ImportErrorRule

有关如何控制导入的详细信息,请参阅Control How MATLAB Imports Your Data

名称-值参数

将可选的参量对组指定为 Name1=Value1,...,NameN=ValueN,其中 Name 是参量名称,Value 是对应的值。名称-值参量必须出现在其他参量之后,但参量对组的顺序无关紧要。

示例: readcell(filename,NumHeaderLines=5) 指示指定文件的前五行是标题行。

在 R2021a 之前,使用逗号分隔每个名称和值,并用引号将 Name 引起来。

示例: readcell(filename,"NumHeaderLines",5) 指示指定文件的前五行是标题行。

文本文件

全部折叠

文件的类型,指定为 "text""spreadsheet"

filename 不包括文件扩展名或者扩展名不是以下任一扩展名时,请指定 FileType 名称-值参量:

  • .txt.dat.csv(用于带分隔符的或等宽文本文件)

  • .xls.xlsb.xlsm.xlsx.xltm.xltx.ods(电子表格文件)

示例: "FileType","text"

带分隔符的文本文件中的字段分隔符,指定为字符串数组、字符向量或字符向量元胞数组。

示例: "Delimiter","|"

示例: "Delimiter",[";","*"]

管理带分隔符的文本文件中的前导分隔符的过程,指定为下表中的值之一。

行为
"keep"保留分隔符。
"ignore"忽略分隔符。
"error"返回错误并取消导入操作。

管理带分隔符的文本文件中的尾部分隔符的过程,指定为下表中的值之一。

行为
"keep"保留分隔符。
"ignore"忽略分隔符。
"error"返回错误并取消导入操作。

管理带分隔符的文本文件中的连续分隔符的过程,指定为下表中的值之一。

行为
"split"将连续分隔符拆分为多个字段。
"join"将多个分隔符合并成一个分隔符。
"error"返回错误并取消导入操作。

文件中的标题行数,指定为正整数。如果未指定,则 readcell 会自动检测文件中标题行的数目。

示例: "NumHeaderLines",7

导入文本数据的类型,指定为以下值之一:

  • "string" - 将文本数据作为字符串数组导入。

  • "char" - 将文本数据作为字符向量导入。

示例: "TextType","char"

导入的日期时间数据的类型,指定为下表中的值之一。

描述
"datetime"

MATLAB datetime 数据类型

有关详细信息,请参阅 datetime

"text"

导入的日期时间数据的类型取决于 TextType 参量中指定的值:

  • 如果 TextType 设置为 "string",则 readcell 会以字符串数组形式返回日期。

  • 如果 TextType 设置为 "char",则 readcell 会以字符向量元胞数组的形式返回日期。

预期的变量或列的数目,指定为正整数。如果未指定,readcell 会自动检测变量或列的数目。

要从文本文件中读取的数据部分,指定为以下形式之一的字符串标量、字符向量或数值向量。

指定 Range 的方式描述

起始单元格

"Cell"[row col]

指定数据的起始单元格:

  • 字符串标量或字符向量,包含使用 Excel A1 表示法的列字母和行号。例如,A5 是第 A 列与第 5 行相交处的单元格的标识符。

  • 二元素数值向量,形式为 [row col],表示起始行和列。

readcell 根据起始单元格自动检测数据范围,从起始单元格开始导入,并在到达最后一个空行或页脚范围时结束。

例如:"A5"[5 1]

矩形范围

"Corner1:Corner2"[r1 c1 r2 c2]

使用以下形式之一的矩形范围指定要读取的精确区域:

  • "Corner1:Corner2" - 使用两个对角指定范围,这两个对角以 Excel A1 表示法定义要读取的区域。例如,"C2:N15"

  • [r1 c1 r2 c2] - 使用包含起始行、起始列、结束行和结束列的四元素数值向量指定范围。例如,[2 3 15 13]

readcell 只读取包含在指定范围内的数据。readcell 将指定范围内的任何空字段作为空元胞导入。

行范围或列范围

"Row1:Row2""Column1:Column2"

通过使用 Excel 行号标识起始行和结束行来指定范围。

readcell 根据指定的行范围自动检测列范围,从第一个非空列开始读取,一直到数据的最后。readcell 为文件中的每列数据创建一个元胞数组列。

例如:"5:500"

也可以通过使用 Excel 列字母或列号标识起始列和结束列来指定范围。

readcell 根据指定的列范围自动检测行范围,从第一个非空行开始读取,一直到数据的最后或页脚范围。

指定范围内的列数必须与 ExpectedNumVariables 属性中指定的数字匹配。

例如:"A:K"

起始行号

n

使用正标量行索引指定包含数据的第一行。

readcell 根据指定的行索引自动检测数据范围,从指定的第一行开始读取,一直到数据的最后或页脚范围。

例如:5

Excel 中的命名范围

"NamedRange"

在 Excel 中,您可以创建名称来标识电子表格中的范围。例如,您可以选择电子表格的一个矩形部分,并将其命名为 "myTable"。如果电子表格中存在此类命名范围,则 readcell 可以使用它的名称来读取范围。

例如:"Range","myTable"

未指定或为空

""

如果未指定或为空,readcell 会自动检测使用的范围。

例如:"Range",""

注意:使用范围是指电子表格中实际包含数据的矩形部分。readcell 通过删减不包含数据的前导和尾随的行和列,自动检测使用范围。只包含空白的文本被视为数据,并会在使用范围内被捕获。

HTTPHTTPS 请求选项,指定为 weboptions 对象。当指定的 filename 是包含协议类型 "http://""https://" 的 Internet URL 时,由 weboptions 对象确定如何导入数据。

要视为空白的字符,指定为包含一个或多个字符的字符向量或字符串标量。

示例: 'Whitespace',' _'

示例: 'Whitespace','?!.,'

行尾字符,指定为字符串数组、字符向量或字符向量元胞数组。

示例: "LineEnding","\n"

示例: "LineEnding","\r\n"

示例: "LineEnding",["\b",":"]

注释样式,指定为字符串数组、字符向量或字符向量元胞数组。对于单行和多行注释,起始标识符必须为第一个非空白字符。对于单行注释,请指定一个标识符,以便将以该标识符开头的行视为注释。对于多行注释,从起始(第一个)标识符到结束(第二个)标识符的行被视为注释。最多只能指定两个由标识符组成的字符向量。

例如,要忽略百分号后面的行作为第一个非空白字符,请将 CommentStyle 指定为 "%"

示例: "CommentStyle",["/*"]

示例: "CommentStyle",["/*","*/"]

与文件关联的字符编码方案,指定为 "system" 或标准字符编码方案名称。如果您没有指定任何编码,则 readcell 在读取文件时将使用自动字符集检测来确定编码。

如果除了导入选项对象外还指定了 Encoding 参量,则 readcell 将使用 Encoding 指定的值,从而覆盖在导入选项中定义的编码。

示例: "Encoding","UTF-8" 使用 UTF-8 作为编码。

示例: "Encoding","system" 使用系统默认编码。

文本文件中持续时间数据的输出数据类型,指定为下表中的值之一。

导入的持续时间数据的类型
"duration"

MATLAB duration 数据类型。

有关详细信息,请参阅 duration

"text"

导入的持续时间数据的类型取决于在 TextType 参量中指定的值:

  • 如果 TextType 设置为 "string",则 readcell 会以字符串数组的形式返回持续时间数据。

  • 如果 TextType 设置为 "char",则 readcell 会以字符向量元胞数组的形式返回持续时间数据。

用于读取日期的区域设置,指定为字符串标量或 xx_YY 形式的字符向量,其中:

  • xx 是指示语言的小写 ISO 639-1 双字母代码。

  • YY 是指示国家/地区的大写 ISO 3166-1 alpha-2 代码。

下表列出了区域设置的某些常用值。

区域设置 语言国家/地区
"de_DE"德语德国
"en_GB"英语英国
"en_US"英语美国
"es_ES"西班牙语西班牙
"fr_FR"法语法国
"it_IT"意大利语意大利
"ja_JP"日语日本
"ko_KR"韩语韩国
"nl_NL"荷兰荷兰
"zh_CN"简体中文中国

使用 %D 格式设定符来将文本读取为 datetime 值时,请使用 DateLocale 指定 readcell 应使用何种区域设置来解释月份和星期几的名称及缩写。

如果除导入选项对象外您还指定了 DateLocale 参量,则 readcell 将使用为 DateLocale 参量指定的值,从而覆盖在导入选项中定义的区域设置。

示例: "DateLocale","ja_JP"

电子表格文件

全部折叠

文件的类型,指定为 "text""spreadsheet"

filename 不包含文件扩展名或扩展名不是以下任一项时,请指定 FileType 名称-值对组参量:

  • .txt.dat.csv(用于带分隔符的或等宽文本文件)

  • .xls.xlsb.xlsm.xlsx.xltm.xltx.ods(电子表格文件)

示例: "FileType","text"

文件中的标题行数,指定为正整数。如果未指定,则 readcell 会自动检测文件中标题行的数目。

示例: "NumHeaderLines",7

导入文本数据的类型,指定为以下值之一:

  • "string" - 将文本数据作为字符串数组导入。

  • "char" - 将文本数据作为字符向量导入。

示例: "TextType","char"

导入的日期时间数据的类型,指定为下表中的值之一。

描述
"datetime"

MATLAB datetime 数据类型

有关详细信息,请参阅 datetime

"text"

导入的日期时间数据的类型取决于 TextType 参量中指定的值:

  • 如果 TextType 设置为 "string",则 readcell 会以字符串数组形式返回日期。

  • 如果 TextType 设置为 "char",则 readcell 会以字符向量元胞数组的形式返回日期。

"exceldatenum"

Excel 日期序列值

"exceldatenum" 仅适用于电子表格文件,对文本文件无效。日期序列值是一个数字,它等于从给定的参照日期开始计算的天数。Excel 日期序列值与 MATLAB 日期序列值使用不同的参照日期。有关 Excel 日期的详细信息,请参阅 Excel 中的 1900 和 1904 日期系统之间的差异

预期的变量或列的数目,指定为正整数。如果未指定,readcell 会自动检测变量或列的数目。

要从中读取数据的工作表,指定为空字符数组、包含工作表名称的字符向量或字符串标量,或表示工作表索引的正整数标量。根据为 Sheet 名称-值参量指定的值,readcell 的行为如下表中所述。

指定的值行为
''(默认值)从第一个工作表导入数据。
工作表名称从具有匹配名称的工作表中导入数据,不考虑电子表格文件中工作表的顺序。
工作表索引从由索引指定的位置的工作表导入数据,不考虑电子表格文件中的工作表名称。

从电子表格文件中读取的数据部分,指定为以下形式之一的字符串标量、字符向量或数值向量。

指定 Range 的方式描述

起始单元格

"Cell"[row col]

将数据的起始单元格指定为:

  • 字符串标量或字符向量,包含使用 Excel A1 表示法的列字母和行号。例如,A5 是第 A 列与第 5 行相交处的单元格的标识符。

  • 二元素数值向量,形式为 [row col],表示起始行和列。

readcell 根据起始单元格自动检测数据范围,从起始单元格开始导入,并在到达最后一个空行或页脚范围时结束。

例如:"A5"[5 1]

矩形范围

"Corner1:Corner2"[r1 c1 r2 c2]

使用以下形式之一的矩形范围指定要读取的精确区域:

  • "Corner1:Corner2" - 使用两个对角指定范围,这两个对角以 Excel A1 表示法定义要读取的区域。例如,"C2:N15"

  • [r1 c1 r2 c2] - 使用包含起始行、起始列、结束行和结束列的四元素数值向量指定范围。例如,[2 3 15 13]

readcell 只读取包含在指定范围内的数据。readcell 将指定范围内的任何空字段作为空元胞导入。

行范围或列范围

"Row1:Row2""Column1:Column2"

通过使用 Excel 行号标识起始行和结束行来指定范围。

readcell 根据指定的行范围自动检测列范围,从第一个非空列开始读取,一直到数据的最后。readcell 为文件中的每列数据创建一个元胞数组列。

例如:"5:500"

也可以通过使用 Excel 列字母或列号标识起始列和结束列来指定范围。

readcell 根据指定的列范围自动检测行范围,从第一个非空行开始读取,一直到数据的最后或页脚范围。

指定范围内的列数必须与 ExpectedNumVariables 属性中指定的数字匹配。

例如:"A:K"

起始行号

n

使用正标量行索引指定包含数据的第一行。

readcell 根据指定的行索引自动检测数据范围,从指定的第一行开始读取,一直到数据的最后或页脚范围。

例如:5

Excel 中的命名范围

"NamedRange"

在 Excel 中,您可以创建名称来标识电子表格中的范围。例如,您可以选择电子表格的一个矩形部分,并将其命名为 "myTable"。如果电子表格中存在此类命名范围,则 readcell 可以使用它的名称来读取范围。

例如:"Range","myTable"

未指定或为空

""

如果未指定或为空,readcell 会自动检测使用的范围。

例如:"Range",""

注意:使用范围是指电子表格中实际包含数据的矩形部分。readcell 通过删减不包含数据的前导和尾随的行和列,自动检测使用范围。只包含空白的文本被视为数据,并会在使用范围内被捕获。

电子表格文件中持续时间数据的输出数据类型,指定为下表中的值之一。

导入的持续时间数据的类型
"duration"

MATLAB duration 数据类型。

有关详细信息,请参阅 duration

"text"

导入的持续时间数据的类型取决于在 TextType 参量中指定的值:

  • 如果 TextType 设置为 "string",则 readcell 会以字符串数组的形式返回持续时间数据。

  • 如果 TextType 设置为 "char",则 readcell 会以字符向量元胞数组的形式返回持续时间数据。

HTTPHTTPS 请求选项,指定为 weboptions 对象。当指定的 filename 是包含协议类型 "http://""https://" 的 Internet URL 时,由 weboptions 对象确定如何导入数据。

读取电子表格数据时启动 Windows 版 Microsoft Excel 实例的标志,指定为以下值之一:

  • 1 (true) - 读取文件时启动 Microsoft Excel 的实例。

  • 0 (false) - 读取文件时不启动 Microsoft Excel 的实例。在此模式下操作时,readcell 功能支持的文件格式和交互式功能(例如公式和宏)有所不同。

UseExcel

true

false

支持的文件格式

.xls, .xlsx, .xlsm, .xltx, .xltm, .xlsb, .ods

.xls, .xlsx, .xlsm, .xltx, .xltm

支持交互功能,例如公式和宏

版本历史记录

在 R2019a 中推出