Main Content

本页的翻译已过时。点击此处可查看最新英文版本。

detectImportOptions

基于文件内容生成导入选项

说明

示例

opts = detectImportOptions(filename) 在文件中找到一个表并返回其导入选项。您可以修改选项对象,并将它与 readtable 一起使用以控制 MATLAB® 如何导入表格数据。返回的选项类型取决于文件扩展名。例如,如果 filename 为电子表格文件,该函数返回 SpreadsheetImportOptions 对象。但是,如果 filename 是文本文件,则该函数返回 DelimitedTextImportOptionsFixedWidthImportOptions 对象;如果 filename 是 XML 文件,则返回 XMLImportOptions 对象。

示例

opts = detectImportOptions(filename,Name,Value) 在由一个或多个 Name,Value 对组参数指定的附加参数的辅助下,在文件中查找表。

示例

全部折叠

检测针对电子表格文件的导入选项,指定要导入的变量,然后读取数据。

根据文件创建导入选项对象。

opts = detectImportOptions('patients.xls')
opts = 
  SpreadsheetImportOptions with properties:

   Sheet Properties:
                        Sheet: ''

   Replacement Properties:
                  MissingRule: 'fill'
              ImportErrorRule: 'fill'

   Variable Import Properties: Set types by name using setvartype
                VariableNames: {'LastName', 'Gender', 'Age' ... and 7 more}
                VariableTypes: {'char', 'char', 'double' ... and 7 more}
        SelectedVariableNames: {'LastName', 'Gender', 'Age' ... and 7 more}
              VariableOptions: Show all 10 VariableOptions 
	Access VariableOptions sub-properties using setvaropts/getvaropts
           VariableNamingRule: 'modify'

   Range Properties:
                    DataRange: 'A2' (Start Cell)
           VariableNamesRange: 'A1'
                RowNamesRange: ''
           VariableUnitsRange: ''
    VariableDescriptionsRange: '' 
	To display a preview of the table, use preview

修改选项对象以指定要导入的变量。

opts.SelectedVariableNames = {'Systolic','Diastolic'};

使用 readtable 以及选项对象导入指定的变量。

T = readtable('patients.xls',opts);
summary(T)
Variables:

    Systolic: 100x1 double

        Values:

            Min         109   
            Median      122   
            Max         138   

    Diastolic: 100x1 double

        Values:

            Min           68  
            Median      81.5  
            Max           99  

创建导入选项,定制多个变量的数据类型,然后读取数据。

根据文本文件创建导入选项对象。

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: Show all 29 VariableOptions 
	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

检查变量 TaxiInTaxiOutType 属性。

getvaropts(opts,{'TaxiIn','TaxiOut'})
ans = 
  1x2 TextVariableImportOptions array with properties:

    Name
    Type
    FillValue
    TreatAsMissing
    QuoteRule
    Prefixes
    Suffixes
    EmptyFieldRule
    WhitespaceRule

将变量 TaxiInTaxiOut 的类型更改为 double

 opts = setvartype(opts,{'TaxiIn','TaxiOut'},'double');

指定要导入和检查的变量的子集。

opts.SelectedVariableNames = {'TaxiIn','TaxiOut'};

使用 readtable 函数以及选项对象导入选定的变量。显示表的摘要。

T = readtable('airlinesmall.csv',opts);
summary(T)
Variables:

    TaxiIn: 123523x1 double

        Values:

            Min             0      
            Median          5      
            Max             1451   
            NumMissing      37383  

    TaxiOut: 123523x1 double

        Values:

            Min             0      
            Median          13     
            Max             755    
            NumMissing      37364  

通过指定导入选项将文本数据作为字符串数据类型导入。

为文件创建选项对象。

opts = detectImportOptions('outages.csv');

使用 readtable 指定要导入的变量,然后显示摘要。所选变量的数据类型是 char

opts.SelectedVariableNames = {'Region','Cause'};
T = readtable('outages.csv',opts);
summary(T)
Variables:

    Region: 1468x1 cell array of character vectors

    Cause: 1468x1 cell array of character vectors

将文本数据作为 string 数据类型导入,然后通过指定 TextType 名称-值对组创建导入选项。

opts = detectImportOptions('outages.csv','TextType','string');

使用 readtable 指定要导入的变量,然后显示摘要。所选变量的数据类型现在是 string

opts.SelectedVariableNames = {'Region','Cause'};
T = readtable('outages.csv',opts);
summary(T)
Variables:

    Region: 1468x1 string

    Cause: 1468x1 string

使用 RegisteredNamespaces 名称-值参数将自定义 XML 命名空间前缀注册到输入文件中的现有命名空间 URL。

从 XML 文件创建一个 XMLImportOptions 对象。将 Street 元素节点的 XPath 表达式指定为 'VariableSelectors' 的值,并将前缀 myPrefix 注册到属于 Street 节点的 URL。

opts = detectImportOptions("students.xml","RegisteredNamespaces", ["myPrefix","https://www.mathworks.com"],...
    "VariableSelectors","//myPrefix:Street")
opts = 
  XMLImportOptions with properties:

   Replacement Properties:
                     MissingRule: "fill"
                 ImportErrorRule: "fill"
                RepeatedNodeRule: "addcol"

   Variable Import Properties: Set types by name using setvartype
                   VariableNames: "Street"
                   VariableTypes: "string"
           SelectedVariableNames: "Street"
                 VariableOptions: Show all 1 VariableOptions 
	Access VariableOptions sub-properties using setvaropts/getvaropts
              VariableNamingRule: "preserve"

   Location Properties:
                   TableSelector: <missing>
                     RowSelector: <missing>
               VariableSelectors: "//myPrefix:Street"
           VariableUnitsSelector: <missing>
    VariableDescriptionsSelector: <missing>
                RowNamesSelector: <missing>
            RegisteredNamespaces: ["myPrefix"    "https://www.mathworks.com"]

使用 readtable 函数以及选项对象导入选定的变量。

T2 = readtable("students.xml",opts)
T2=7×1 table
          Street       
    ___________________

    "591 Spring Lane"  
    "4641 Pearl Street"
    "30 Highland Road" 
    "3388 Moore Avenue"
    "3388 Moore Avenue"
    "22 Angie Drive"   
    "65 Decatur Lane"  

输入参数

全部折叠

要读取的文件的名称,指定为字符向量或字符串标量。

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

位置

形式

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

指定 filename 中文件的名称。

示例:'myFile.txt'

文件夹中的文件

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

示例:'C:\myFolder\myFile.xlsx'

示例:'\imgDir\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 Storagewasbwasbs
HDFS™hdfs

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

示例:'s3://bucketname/path_to_file/my_file.csv'

如果 filename 包含文件扩展名,则 detectImportOptions 基于扩展名确定文件格式。否则,您必须指定 'FileType' 名称-值对组以指示文件类型。

detectImportOptions 函数支持以下文件扩展名:.txt.dat.csv.xls.xlsb.xlsm.xlsx.xltm.xltx.ods.xml

注意

只有在使用了 Windows® 版 Excel® 的平台上才支持文件扩展台 .xlsb.ods

数据类型: char | string

名称-值对组参数

指定可选的、以逗号分隔的 Name,Value 对组参数。Name 为参数名称,Value 为对应的值。Name 必须放在引号中。您可采用任意顺序指定多个名称-值对组参数,如 Name1,Value1,...,NameN,ValueN 所示。

示例: 'FileType','spreadsheet'
所有支持的文件类型

全部折叠

文件类型,指定为以逗号分隔的对组,该对组由 'FileType' 和下列值之一组成。

文件的导入选项
'spreadsheet'

返回 SpreadsheetImportOptions 对象。

'text'

根据文本文件的布局,返回 DelimitedTextImportOptionsFixedWidthImportOptions 对象。

'delimitedtext'

返回 DelimitedTextImportOptions 对象。对于用分隔符分隔列的文本文件,请使用此选项。

'fixedwidth'

返回 FixedWidthImportOptions 对象。对于具有等宽列的文本文件,请使用此选项。

'xml'

返回 XMLImportOptions 对象。对 XML 文件使用此选项。

filename 不包含文件扩展名时,或当扩展名不是以下项之一时,请使用 'FileType' 名称-值对组参数:

  • .txt.dat.csv(适用于文本文件)

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

  • .xml(适用于 XML 文件)

只有在使用了 Windows 版 Excel 的平台上才支持文件扩展台 .xlsb.ods

示例: 'FileType','text'

数据类型: char | string

导入的文本数据的类型,指定为以逗号分隔的对组,其中包含 'TextType''char''string' 中的任一项。

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

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

示例: 'TextType','char'

导入的日期和时间数据的类型,指定为以逗号分隔的对组,其中包含 'DatetimeType' 和下列值之一:'datetime''text''exceldatenum'。值 'exceldatenum' 仅适用于电子表格文件,对文本文件无效。

导入的日期和时间数据的类型
'datetime'

MATLAB datetime 数据类型

有关详细信息,请参阅 datetime

'text'

如果将 'DatetimeType' 指定为 'text',则导入的日期和时间数据的类型取决于 'TextType' 参数中指定的值:

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

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

'exceldatenum'

Excel 日期序列值

日期序列值是一个数字,它等于从给定的参照日期开始计算的天数。Excel 日期序列值与 MATLAB 日期序列值使用不同的参照日期。有关 Excel 日期的详细信息,请参阅 https://support.microsoft.com/en-us/kb/214330

数据类型: char | string

读取第一行以作为变量名称的指示符,指定为逗号分隔的对组,包含 'ReadVariableNames'truefalse。如果未指定,readtable 将自动检测是否存在变量名称。

指示符

说明

true

当要读取的区域的第一行包含表格的变量名称时使用。readtable 将使用检测到的变量名称为 T 中的每列创建一个变量。

false

当要读取的区域的第一行包含表格中的数据时使用。readtable 将创建 'Var1',...,'VarN' 形式的默认变量名称,其中 N 是变量的数量。

未指定 未指定时,导入函数会自动检测 truefalse,并相应地继续后续步骤。

数据类型: logical

保留变量名称的标志,指定为以逗号分隔的对组,由 VariableNamingRule'modify''preserve' 组成。

  • 'modify' - 将无效变量名称(由 isvarname 函数确定)转换为有效的 MATLAB 标识符。

  • 'preserve' - 保留作为无效 MATLAB 标识符的变量名称,如包含空白和非 ASCII 字符的变量名称。

从 R2019b 开始,变量名称和行名称可以包含任何字符,包括空格和非 ASCII 字符。此外,它们可以由任何字符(而不仅仅是字母)开头。变量名称和行名称可以不是有效的 MATLAB 标识符(由 isvarname 函数决定)。要保留这些变量名称和行名称,请将 VariableNamingRule 的值设置为 'preserve'

数据类型: char | string

读取第一列以作为行名称的指示符,指定为逗号分隔的对组,包含 'ReadRowNames'falsetrue

指示符

说明

false

当要读取的区域第一列包含的是数据而不是表的行名称时使用。

true

当要读取的区域第一列包含表的行名称时使用。

未指定未指定时,导入函数假设为 false

数据类型: logical

管理缺失数据的过程,指定为下表中的值之一。

缺失规则行为
'fill'

FillValue 属性的内容替代缺失的数据。

FillValue 属性在要导入的变量的 VariableImportOptions 对象中指定。有关访问 FillValue 属性的详细信息,请参阅 getvaropts

'error'停止导入并显示一条错误消息,指出缺失的记录和字段。
'omitrow'忽略包含缺失数据的行。
'omitvar'忽略包含缺失数据的变量。

示例: opts.MissingRule = 'omitrow';

数据类型: char | string

处理导入错误的过程,指定为下表中的值之一。

导入错误规则行为
'fill'

FillValue 属性的内容替代出现错误的数据。

FillValue 属性在要导入的变量的 VariableImportOptions 对象中指定。有关访问 FillValue 属性的详细信息,请参阅 getvaropts

'error'停止导入并显示一条错误消息,指出导致出错的记录和字段。
'omitrow'忽略发生错误的行。
'omitvar'忽略发生错误的变量。

示例: opts.ImportErrorRule = 'omitvar';

数据类型: char | string

文本和电子表格文件

全部折叠

需要的变量数目,指定为包含 'ExpectedNumVariables' 和正整数的逗号分隔对组。如果未指定,则导入函数会自动检测变量数目。

数据类型: single | double

文件中标题行的数目,指定为以逗号分隔的对组,其中包含 'NumHeaderLines' 和一个正整数。如果未指定,则导入函数会自动检测文件中标题行的数目。

示例: 'NumHeaderLines',7

数据类型: single | double

要从文本文件或电子表格文件中读取的数据部分,指定为以逗号分隔的对组,其中包含 'Range' 和采用以下形式之一的字符向量、字符串标量或数值向量。

指定 Range 的方式说明

起始单元格

'Cell'[row col]

将数据的起始单元格指定为字符向量、字符串标量或二元素数值向量。

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

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

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

例如:'A5'[5 1]

矩形范围

'Corner1:Corner2'[r1 c1 r2 c2]

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

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

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

导入函数只读取指定范围内包含的数据。指定范围内的任何空字段都作为缺失单元导入。

行范围或列范围

'Row1:Row2''Column1:Column2'

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

根据指定的行范围,导入函数通过从第一个非空列开始读取,一直到数据的最后,从而自动检测列范围,并为每一列创建一个变量。

示例:'5:500'

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

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

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

示例:'A:K'

起始行号

n

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

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

示例:5

Excel 中的命名范围

'NamedRange'

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

示例: 'Range','myTable'

未指定或为空

''

如果未指定,则导入函数会自动检测使用的范围。

示例: 'Range',''

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

数据类型: char | string | double

仅限电子表格文件的参数

全部折叠

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

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

数据类型: char | string | single | double

要导入的数据的位置,指定为字符向量、字符串标量、字符向量元胞数组、字符串数组、正整数标量或由正整数标量组成的 N×2 数组。使用以下形式之一指定 DataRange

行为

'Cell'n

起始单元格或起始行

使用 Excel A1 表示法指定数据的起始单元。例如,A5 是第 A 列与第 5 行相交处的单元格的标识符。

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

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

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

例如:'A5'5

'Corner1:Corner2'

矩形范围

使用矩形范围格式指定确切范围,其中 Corner1Corner2 是定义要读取的区域的两个对角。

导入函数只读取指定范围内包含的数据。指定范围内的任何空字段都作为缺失单元导入。

列数必须与 NumVariables 属性中的指定的数字匹配。

示例:'A5:K50'

'Row1:Row2''Column1:Column2'

行范围或列范围

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

根据指定的行范围,导入函数通过从第一个非空列开始读取,一直到数据的最后,从而自动检测列范围,并为每一列创建一个变量。

示例:'5:500'

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

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

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

示例:'A:K'

[n1 n2; n3 n4;...]

多个行范围

使用包含 N 个不同行范围的 N×2 数组来指定要读取的多个行范围

包含多个行范围的有效数组必须满足以下条件:

  • 以递增顺序指定行范围,也就是说,数组中指定的第一个行范围出现在文件中的其他行范围之前。

  • 仅包含不重叠的行范围。

Inf 只能用来指示指定了多个行范围的数组中的最后一个范围。例如,[1 3; 5 6; 8 Inf]

示例:[1 3; 5 6; 8 Inf]

''

未指定或为空

不获取任何数据。

示例:''

数据类型: char | string | cell | single | double

行名称的位置,指定为字符向量、字符串标量、正整数标量或空字符数组。将 RowNamesRange 指定为下表中的值之一。

行为

'Cell'

使用 Excel A1 表示法指定数据的起始单元。例如,A5 是第 A 列与第 5 行相交处的单元格的标识符。

导入函数为数据中的每个变量标识一个名称。

示例:'A5'

'Corner1:Corner2'

矩形范围

使用矩形范围格式指定确切范围,其中 Corner1Corner2 是定义要读取的区域的两个对角。

RowNamesRange 中包含的行数必须与数据行的数量匹配,而且 RowNamesRange 指示的范围只能跨一列。

示例:'A5:A50'

'Row1:Row2'

行范围

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

行名称必须在单独一列中。

示例:'5:50'

n

数字索引

使用正标量列索引指定包含行名称的列。

示例:5

''

未指定或为空

指示没有行名称。

示例:''

数据类型: char | single | double

变量名称的位置,指定为字符向量、字符串标量、正整数标量或空字符数组。将 VariableNamesRange 指定为下表中的值之一。

行为

'Cell'

使用 Excel A1 表示法指定数据的起始单元。例如,A5 是第 A 列与第 5 行相交处的单元格的标识符。

导入函数为数据中的每个变量读取一个名称。

示例:'A5'

'Corner1:Corner2'

矩形范围

使用矩形范围格式指定确切范围,其中 Corner1Corner2 是定义要读取的区域的两个对角。

列数必须与 NumVariables 属性中指定的数字匹配,而且范围只能跨一行。

示例:'A5:K5'

'Row1:Row2'

行范围

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

必须为一行。

示例:'5:5'

n

数字索引

使用正标量行索引指定包含变量名称的行。

示例:5

''

未指定或为空

指示没有变量名称。

示例:''

数据类型: char | single | double

变量单位的位置,指定为字符向量、字符串标量、正整数标量或空字符数组。将 VariableUnitsRange 指定为下表中的值之一。

行为

'Cell'

使用 Excel A1 表示法指定数据的起始单元。例如,A5 是第 A 列与第 5 行相交处的单元格的标识符。

导入函数为数据中的每个变量读取一个单位。

示例:'A5'

'Corner1:Corner2'

矩形范围

使用矩形范围格式指定确切范围,其中 Corner1Corner2 是定义要读取的区域的两个对角。

列数必须与 NumVariables 属性中指定的数字匹配,而且范围只能跨一行。

示例:'A5:K5'

'Row1:Row2'

行范围

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

必须为一行。

示例:'5:5'

n

数字索引

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

示例:5

''

未指定或为空

指示没有变量单位。

示例:''

数据类型: char | string | single | double

变量描述的位置,指定为字符向量、字符串标量、正整数标量或空字符数组。将 VariableDescriptionRange 指定为下表中的值之一。

行为

'Cell'

使用 Excel A1 表示法指定数据的起始单元。例如,A5 是第 A 列与第 5 行相交处的单元格的标识符。

导入函数为数据中的每个变量读取一个描述。

示例:'A5'

'Corner1:Corner2'

矩形范围

使用矩形范围格式指定确切范围,其中 Corner1Corner2 是定义要读取的区域的两个对角。

列数必须与 NumVariables 属性中指定的数字匹配,而且范围只能跨一行。

示例:'A5:K5'

'Row1:Row2'

行范围

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

必须为一行。

示例:'5:5'

n

数字索引

使用正标量行索引指定包含描述的行。

示例:5

''

未指定或为空

指示没有变量描述。

示例:''

数据类型: char | string | single | double

仅限文本文件的参数

全部折叠

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

示例: 'Delimiter','|'

示例: 'Delimiter',{';','*'}

数据类型: char | string | cell

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

前导分隔符规则行为
'keep'保留分隔符。
'ignore'忽略分隔符。
'error'返回错误并中止导入操作。

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

前导分隔符规则行为
'keep'保留分隔符。
'ignore'忽略分隔符。
'error'返回错误并中止导入操作。

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

连续分隔符规则行为
'split'将连续分隔符拆分为多个字段。
'join'将多个分隔符合并成一个分隔符。
'error'返回错误并中止导入操作。

数据类型: char | string

等宽文本文件中变量的字段宽度,指定为正整数值向量。该向量中的每个正整数对应于一个字段中构成变量的字符数。对于 VariableNames 属性中指定的每个变量,VariableWidths 属性中均包含一个对应的条目。

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

示例: 'Whitespace',' _'

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

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

示例: 'LineEnding','\n'

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

示例: 'LineEnding',{'\b',':'}

数据类型: char | string | cell

与文件关联的字符编码方案,指定为以逗号分隔的对组,其中包含 'Encoding''system' 或标准字符编码方案名称。

如果您没有指定任何编码,则该函数在读取文件时将使用自动字符集检测来确定编码。

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

数据类型: char | string

注释样式,指定为字符向量、字符串标量、字符向量元胞数组或字符串数组。

例如,要忽略同一行上百分号后面的文本,请将 CommentStyle 指定为 '%'

示例: 'CommentStyle',{'/*'}

数据类型: char | string | cell

来自文本文件的持续时间数据的输出数据类型,指定为以逗号分隔的对组,其中包含 'DurationType''duration''text'

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

MATLAB duration 数据类型

有关详细信息,请参阅 duration

'text'

如果将 'DurationType' 指定为 'text',则导入的持续时间数据的类型取决于 'TextType' 参数中指定的值:

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

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

数据类型: char | string

处理数据中的附加列的过程,指定为下表中的值之一。

附加列规则行为
'addvars'

要导入附加列,需要创建新变量。如果有 N 个附加列,将以 'ExtraVar1', 'ExtraVar2',..., 'ExtraVarN' 的形式导入新变量。

注意:附加列作为 char 数据类型的文本导入。

'ignore'忽略附加列数据。
'wrap'将附加列数据换行到新记录中。此操作不会更改变量的数量。
'error'显示错误消息并中止导入操作。

数据类型: char | string

要解释为缺失数据的文本,指定为字符向量、字符串标量、字符向量元胞数组或字符串数组。

当导入函数发现缺失实例后,将根据 MissingRule 属性中的指定确定适当的操作。

示例: 'TreatAsMissing',{'NA','TBD'} 指示导入函数将 NATBD 的任何实例都视为缺失字段。

数据类型: char | string | cell

用于读取日期的区域设置,指定为逗号分隔的对组,其中包含 'DateLocale' 和一个 xx_YY 形式的字符向量或字符串标量,其中:

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

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

有关区域设置的常见值的列表,请参阅 datetime 函数的 Locale 名称-值对组参数。

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

如果除 opts 导入选项外您还指定了 DateLocale 参数,则导入函数将使用为 DateLocale 参数指定的值,而覆盖导入选项中定义的区域设置。

示例: 'DateLocale','ja_JP'

表示数值变量中千分位的字符,指定为字符向量或字符串标量。千分位字符作为视觉分隔符,将数字按三位数一组进行分组。导入函数使用 ThousandsSeparator 属性中的字符来解释要导入的数字。

数据类型: char | string

表示数值变量中小数分隔符的字符,指定为字符向量或字符串标量。导入函数使用 DecimalSeparator 属性来区分数字的整数部分和小数部分。

转换为整数数据类型时,带小数部分的数字将被舍入为最接近的整数。

数据类型: char | string

从数值变量中删除非数值字符,指定为逻辑值 truefalse

数据类型: logical

十六进制数据的输出数据类型,指定为以逗号分隔的对组,其中包含 'HexType' 和下表中列出的值之一。

输入文件以文本形式表示十六进制值,使用 0x0X 作为前缀,以字符 0-9a-fA-F 作为数字。(大写和小写字母表示相同的数字 - 例如,'0xf''0xF' 都表示 15。)

导入函数将十六进制值转换为由 'HexType' 的值指定的数据类型。

'HexType' 的值

输出表变量的数据类型

'auto'

自动检测到的数据类型

'text'

未更改的输入文本

'int8'

8 位有符号整数

'int16'

16 位有符号整数

'int32'

32 位有符号整数

'int64'

64 位有符号整数

'uint8'

8 位无符号整数

'uint16'

16 位无符号整数

'uint32'

32 位无符号整数

'uint64'

64 位无符号整数

示例: 'HexType','uint16' 将输出表中表示十六进制值的文本(如 '0xFF')转换为 16 位无符号整数(如 255)。

数据类型: char | string

二进制数据的输出数据类型,指定为以逗号分隔的对组,其中包含 'BinaryType' 和下表中列出的值之一。

输入文件以文本形式表示二进制值,使用 0b0B 作为前缀,以字符 01 作为数字。

导入函数将二进制值转换为由 'BinaryType' 的值指定的数据类型。

'BinaryType' 的值

输出表变量的数据类型

'auto'

自动检测到的数据类型

'text'

未更改的输入文本

'int8'

8 位有符号整数

'int16'

16 位有符号整数

'int32'

32 位有符号整数

'int64'

64 位有符号整数

'uint8'

8 位无符号整数

'uint16'

16 位无符号整数

'uint32'

32 位无符号整数

'uint64'

64 位无符号整数

示例: 'BinaryType','uint16' 将输出表中表示二进制值的文本(如 '0b11111111')转换为 16 位无符号整数(如 255)。

数据类型: char | string

仅 XML 文件

全部折叠

导入属性,指定为逗号分隔的对组,包含 'ImportAttributes'1 (true) 或 0 (false)。如果指定 false,则读取函数不会将输入文件中的 XML 属性作为输出表中的变量导入。

示例: 'ImportAttributes',false

属性后缀,指定为逗号分隔的对组,包含 'AttributeSuffix' 和一个字符向量或字符串标量。此参数指定读取函数追加到与输入 XML 文件中的属性对应的所有表变量的后缀。如果未指定 'AttributeSuffix',则读取函数默认将后缀 'Attribute' 附加到与输入 XML 文件中的属性对应的所有变量名称。

示例: 'AttributeSuffix','_att'

表行 XML 节点名称,指定为逗号分隔的对组,包含 'RowNodeName' 和一个字符向量或字符串标量。此参数指定界定输出表行的 XML 节点名称。

示例: 'RowNodeName','XMLNodeName'

表行 XPath 表达式,指定为字符向量或字符串标量,读取函数使用它来选择输出表的各个行。您必须将 RowSelector 指定为有效的 XPath 版本 1.0 表达式。

示例: 'RowSelector','/RootNode/ChildNode'

表变量 XML 节点名称,指定为以逗号分隔的对组,包含 'VariableNodeNames' 和一个字符向量元胞数组或字符串数组。此参数指定读取函数用于标识输出表中作为变量读取的 XML 节点的 XML 节点名称。

示例: 'VariableNodeNames',{'XMLNodeName1','XMLNodeName2'}

示例: 'VariableNodeNames',"XMLNodeName"

示例: 'VariableNodeNames',["XMLNodeName1","XMLNodeName2"]

表变量 XPath 表达式,指定为字符向量元胞数组或字符串数组,读取函数使用它来选择表变量。您必须将 VariableSelectors 指定为有效的 XPath 版本 1.0 表达式。

示例: 'VariableSelectors',{'/RootNode/ChildNode'}

示例: 'VariableSelectors',"/RootNode/ChildNode"

示例: 'VariableSelectors',["/RootNode/ChildNode1","/RootNode/ChildNode2"]

表 XML 节点名称,指定为逗号分隔的对组,其中包含 'TableNodeName' 和一个字符向量或字符串标量。此参数指定读取函数应读取到表的输入结构体中的节点。

示例: 'TableNodeName','NodeName'

表数据 XPath 表达式,指定为字符向量或字符串标量,读取函数使用它来选择输出表数据。您必须将 TableSelector 指定为有效的 XPath 版本 1.0 表达式。

示例: 'TableSelector','/RootNode/ChildNode'

变量单位 XPath,指定为字符向量或字符串标量,读取函数使用它来选择表变量单位。您必须将 VariableUnitsSelector 指定为有效的 XPath 版本 1.0 表达式。

示例: 'VariableUnitsSelector','/RootNode/ChildNode'

变量描述 XPath 表达式,指定为字符向量或字符串标量,读取函数使用它来选择表变量描述。您必须将 VariableDescriptionsSelector 指定为有效的 XPath 版本 1.0 表达式。

示例: 'VariableDescriptionsSelector','/RootNode/ChildNode'

表行名称 XPath 表达式,指定为字符向量或字符串标量,读取函数使用它来选择表行的名称。您必须将 RowNamesSelector 指定为有效的 XPath 版本 1.0 表达式。

示例: 'RowNamesSelector','/RootNode/ChildNode'

处理表的给定行中重复 XML 节点的过程,指定为 'addcol''ignore''error'

重复节点规则

行为

'addcol'

在表中的变量标题下为重复节点添加列。将 'RepeatedNodeRule' 的值指定为 'addcol' 不会在表中为重复节点创建单独变量。

'ignore'

跳过导入重复节点。

'error'显示错误消息并中止导入操作。

示例: 'RepeatedNodeRule','ignore'

注册的 XML 命名空间前缀集,指定为由 RegisteredNamespaces 和前缀数组组成的以逗号分隔的对组。读取函数在计算 XML 文件的 XPath 表达式时使用这些前缀。将命名空间前缀及其关联的 URL 指定为 N×2 字符串数组。在计算由选择器名称-值参数(例如 readstructStructSelectorreadtablereadtimetableVariableSelectors)指定的 XPath 表达式时,可以使用 RegisteredNamespaces

默认情况下,读取函数会自动检测要注册以用于 XPath 计算的命名空间前缀,但您也可以使用 RegisteredNamespaces 名称-值参数注册新命名空间前缀。当 XML 节点有命名空间 URL 但在 XML 文件中没有声明的命名空间前缀时,您可以注册新命名空间前缀。

例如,对名为 example.xml 的不包含命名空间前缀的 XML 文件计算 XPath 表达式。将 'RegisteredNamespaces' 指定为 [“myprefix”, “https://www.mathworks.com”] 以将前缀 myprefix 赋给 URL https://www.mathworks.com

T = readtable("example.xml", "VariableSelector", "/myprefix:Data",...
 "RegisteredNamespaces", [“myprefix”, “https://www.mathworks.com”])

示例: 'RegisteredNamespaces',[“myprefix”, “https://www.mathworks.com”]

输出参数

全部折叠

指定文件的导入选项,以 SpreadsheetImportOptionsDelimitedTextImportOptionsFixedWidthImportOptionsXMLImportOptions 对象形式返回。选项对象的类型取决于指定文件的类型。对于文本文件(.txt.dat.csv),detectImportOptions 函数返回 DelimitedTextImportOptionsFixedWidthImportOptions 对象。对于电子表格文件(.xls.xlsb.xlsm.xlsx.xltm.xltx.ods),detectImportOptions 函数返回 SpreadsheetImportOptions 对象。对于 XML 文件 (.xml),detectImportOptions 返回 XMLImportOptions 对象。

提示

  • 在创建导入选项对象后更新属性值:不推荐使用圆点表示法更新由 detecImportOptions 创建的导入选项对象的属性。当您使用圆点表示法设置属性时,MATLAB 不会重新检测文件的所有导入选项。因此,要更新和重新检测所有属性,必须使用名称-值参数指定新值。例如,按如下方式更新 ConsecutiveDelimitersRule 属性的值并重新检测导入选项。

    opts = detectImportOptions(__,'ConsecutiveDelimitersRule','join')

  • XPath 选择器名称-值参数(例如 RowSelectorVariableSelector)支持以下 XPath 语法。

    • 要选择其名称与您要选择的节点匹配的每个节点,而无论它在文档中的位置如何,请使用 "//myNode" 语法。您可以使用 "//myNode" 省略在要选择的节点前面的 XPath 表达式。

    • 要读取文件中一个父节点下的几个同级节点之一,您可以指定 ChildNode[n],其中 n 对应于要进行索引的同级节点。例如,路径 "/RootNode/ChildNode[2]" 选择其父元素为 RootNode 的第二个 ChildNode 元素。

    • 要读取属于输入 XML 文件中某元素节点的属性的值,请在该属性的名称前指定 @。例如,"/RootNode/ChildNode[2]/@AttributeName" 选择属于其父元素为 RootNode 的第二个 ChildNode 元素的属性 AttributeName

在 R2016b 中推出