Main Content

本页翻译不是最新的。点击此处可查看最新英文版本。

textscan

从文本文件或字符串读取格式化数据

说明

示例

C = textscan(fileID,formatSpec) 将已打开的文本文件中的数据读取到元胞数组 C。该文本文件由文件标识符 fileID 指示。使用 fopen 可打开文件并获取 fileID 值。完成文件读取后,请调用 fclose(fileID) 来关闭文件。

textscan 尝试将文件中的数据与 formatSpec 中的转换设定符匹配。textscan 函数在整个文件中按 formatSpec 重复扫描数据,直至 formatSpec 找不到匹配的数据时才停止。

示例

C = textscan(fileID,formatSpec,N)formatSpec 读取文件数据 N 次,其中 N 是一个正整数。要在 N 个周期后从文件读取其他数据,请使用原 fileID 再次调用 textscan 进行扫描。如果通过调用具有相同文件标识符 (fileID) 的 textscan 恢复文件的文本扫描,则 textscan 将在上次终止读取的点处自动恢复读取。

示例

C = textscan(chr,formatSpec) 将字符向量 chr 中的文本读取到元胞数组 C 中。从字符向量读取文本时,对 textscan 的每一次重复调用都会从开头位置重新开始扫描。要从上次位置重新开始扫描,需要指定 position 输出参数。

textscan 尝试将字符向量 chr 中的数据与 formatSpec 中指定的格式匹配。

C = textscan(chr,formatSpec,N)formatSpec N 次,其中 N 是一个正整数。

示例

C = textscan(___,Name,Value) 支持上述语法中的任何输入参数,且可使用一个或多个 Name,Value 对组参数指定选项。

示例

[C,position] = textscan(___) 在扫描结束时返回文件或字符向量中的位置作为第二个输出参数。对于文件,该值等同于调用 textscan 后再运行 ftell(fileID) 所返回的值。对于字符向量,position 指示 textscan 读取了多少个字符。

示例

全部折叠

读取包含浮点数的字符向量。

chr = '0.41 8.24 3.57 6.24 9.27';
C = textscan(chr,'%f');

formatSpec 中的设定符 '%f' 指示 textscanchr 中的每个字段与一个双精度浮点数进行匹配。

显示元胞数组 C 的内容。

celldisp(C)
 
C{1} =
 
    0.4100
    8.2400
    3.5700
    6.2400
    9.2700

 

读取相同字符向量,将每个值截短至一位小数。

C = textscan(chr,'%3.1f %*1d');

设定符 %3.1f 指示字段宽度为 3 位数,精度为 1。textscan 函数读取全部 3 位数,包括小数点和小数点后的 1 位数。设定符 %*1d 指示 textscan 跳过其余位数。

显示元胞数组 C 的内容。

celldisp(C)
 
C{1} =
 
    0.4000
    8.2000
    3.5000
    6.2000
    9.2000

 

读取一个表示一组十六进制数的字符向量。表示十六进制数的文本包括数字 0-9,字母 a-fA-F,以及可选的前缀 0x0X

要将 hexnums 中的字段与十六进制数匹配,请使用 '%x' 设定符。textscan 函数将字段转换为无符号 64 位整数。

hexnums = '0xFF 0x100 0x3C5E A F 10';
C = textscan(hexnums,'%x')
C = 1x1 cell array
    {6x1 uint64}

C 的内容显示为行向量。

transpose(C{:})
ans = 1x6 uint64 row vector

     255     256   15454      10      15      16

您可以将字段转换为 8、16、32 或 64 位的有符号或无符号整数。要将 hexnums 中的字段转换为有符号 32 位整数,请使用 '%xs32' 设定符。

C = textscan(hexnums,'%xs32');
transpose(C{:})
ans = 1x6 int32 row vector

     255     256   15454      10      15      16

您还可以指定用来解释输入的字段宽度。在这种情况下,前缀将计入字段宽度。例如,如果您将字段宽度设置为三,如在 %3x 中所示,则 textscan 将文本 '0xAF 100' 拆分为三个文本片段,即 '0xA''F''100'。它将这三个文本片段视为不同的十六进制数。

C = textscan('0xAF 100','%3x');
transpose(C{:})
ans = 1x3 uint64 row vector

    10    15   256

读取一个表示一组二进制数的字符向量。表示二进制数的文本包括数字 01,以及可选的前缀 0b0B

要将 binnums 中的字段与二进制数匹配,请使用 '%b' 设定符。textscan 函数将字段转换为无符号 64 位整数。

binnums = '0b101010 0b11 0b100 1001 10';
C = textscan(binnums,'%b')
C = 1x1 cell array
    {5x1 uint64}

C 的内容显示为行向量。

transpose(C{:})
ans = 1x5 uint64 row vector

   42    3    4    9    2

您可以将字段转换为 8、16、32 或 64 位的有符号或无符号整数。要将 binnums 中的字段转换为有符号 32 位整数,请使用 '%bs32' 设定符。

C = textscan(binnums,'%bs32');
transpose(C{:})
ans = 1x5 int32 row vector

   42    3    4    9    2

您还可以指定用来解释输入的字段宽度。在这种情况下,前缀将计入字段宽度。例如,如果您将字段宽度设置为三,如在 %3b 中所示,则 textscan 将文本 '0b1010 100' 拆分为三个文本片段,即 '0b1''010''100'。它将这三个文本片段视为不同的二进制数。

C = textscan('0b1010 100','%3b');
transpose(C{:})
ans = 1x3 uint64 row vector

   1   2   4

加载数据文件,并读取具有适当类型的每一列。

加载文件 scan1.dat 并在文本编辑器中预览其内容。屏幕截图如下所示。

 filename = 'scan1.dat';

打开文件,用正确的转换设定符读取每一列。textscan 返回一个 1-by-9 元胞数组 C

fileID = fopen(filename);
C = textscan(fileID,'%s %s %f32 %d8 %u %f %f %s %f');
fclose(fileID);
whos C
  Name      Size            Bytes  Class    Attributes

  C         1x9              2105  cell               

查看 C 中的每个元胞的 MATLAB® 数据类型。

C
C=1×9 cell array
    {3x1 cell}    {3x1 cell}    {3x1 single}    {3x1 int8}    {3x1 uint32}    {3x1 double}    {3x1 double}    {3x1 cell}    {3x1 double}

检查各个条目。请注意,C{1}C{2} 为元胞数组。C{5} 的数据类型为 uint32,因此 C{5} 的前两个元素为 32 位无符号整数的最大值或 intmax('uint32')

celldisp(C)
 
C{1}{1} =
 
09/12/2005
 
 
C{1}{2} =
 
10/12/2005
 
 
C{1}{3} =
 
11/12/2005
 
 
C{2}{1} =
 
Level1
 
 
C{2}{2} =
 
Level2
 
 
C{2}{3} =
 
Level3
 
 
C{3} =
 
   12.3400
   23.5400
   34.9000

 
 
C{4} =
 
   45
   60
   12

 
 
C{5} =
 
   4294967295
   4294967295
       200000

 
 
C{6} =
 
   Inf
  -Inf
    10

 
 
C{7} =
 
       NaN
    0.0010
  100.0000

 
 
C{8}{1} =
 
Yes
 
 
C{8}{2} =
 
No
 
 
C{8}{3} =
 
No
 
 
C{9} =
 
   5.1000 + 3.0000i
   2.2000 - 0.5000i
   3.1000 + 0.1000i

 

从前一示例的第二列数据的每个字段中删除字面文本 'Level'。下面显示文件的预览。

打开文件,并匹配 formatSpec 输入中的字面文本。

filename = 'scan1.dat';
fileID = fopen(filename);
C = textscan(fileID,'%s Level%d %f32 %d8 %u %f %f %s %f');
fclose(fileID);
C{2}
ans = 3x1 int32 column vector

   1
   2
   3

查看 C 中的第二个元胞的 MATLAB® 数据类型。1-by-9 元胞数组 C 的第二个元胞的数据类型现在为 int32

disp( class(C{2}) )
int32

将前一示例中文件的第一列读取到元胞数组中,跳过行的其余部分。

filename = 'scan1.dat';
fileID = fopen(filename);
dates = textscan(fileID,'%s %*[^\n]');
fclose(fileID);
dates{1}
ans = 3x1 cell
    {'09/12/2005'}
    {'10/12/2005'}
    {'11/12/2005'}

textscan 返回一个日期元胞数组。

加载文件 data.csv 并在文本编辑器中预览其内容。屏幕截图如下所示。请注意该文件包含逗号分隔的数据以及空值。

读取该文件,将空元胞转换为 -Inf

filename = 'data.csv';
fileID = fopen(filename);
C = textscan(fileID,'%f %f %f %f %u8 %f',...
'Delimiter',',','EmptyValue',-Inf);
fclose(fileID);
column4 = C{4}, column5 = C{5}
column4 = 2×1

     4
  -Inf

column5 = 2x1 uint8 column vector

    0
   11

textscan 返回 1-by-6 元胞数组 Ctextscan 函数将 C{4} 中的空值转换为 -Inf,其中 C{4} 与浮点格式关联。因为 MATLAB® 将无符号整数 -Inf 表示为 0,所以 textscanC{5} 中的空值转换为 0 而不是 -Inf

加载文件 data2.csv 并在文本编辑器中预览其内容。屏幕截图如下所示。请注意,该文件包含可以解释为注释和其他项(如 'NA''na')的数据,这些数据可能表示空字段。

filename = 'data2.csv';

指定 textscan 应视为注释或空值的输入,并将该数据扫描到 C 中。

fileID = fopen(filename);
C = textscan(fileID,'%s %n %n %n %n','Delimiter',',',...
'TreatAsEmpty',{'NA','na'},'CommentStyle','//');
fclose(fileID);

显示输出。

celldisp(C)
 
C{1}{1} =
 
abc
 
 
C{1}{2} =
 
def
 
 
C{2} =
 
     2
   NaN

 
 
C{3} =
 
   NaN
     5

 
 
C{4} =
 
     3
     6

 
 
C{5} =
 
     4
     7

 

加载文件 data3.csv 并在文本编辑器中预览其内容。屏幕截图如下所示。请注意,该文件包含重复的分隔符。

filename = 'data3.csv';

要将重复的逗号视为单个分隔符,请使用 MultipleDelimsAsOne 参数并将值设置为 1 (true)。

fileID = fopen(filename);
C = textscan(fileID,'%f %f %f %f','Delimiter',',',...
'MultipleDelimsAsOne',1);
fclose(fileID);


celldisp(C)
 
C{1} =
 
     1
     5

 
 
C{2} =
 
     2
     6

 
 
C{3} =
 
     3
     7

 
 
C{4} =
 
     4
     8

 

加载此示例的数据文件 grades.txt 并在文本编辑器中预览其内容。屏幕截图如下所示。请注意,该文件包含重复的分隔符。

filename = 'grades.txt';

使用格式 '%s' 四次读取列标题。

fileID = fopen(filename);
formatSpec = '%s';
N = 4;
C_text = textscan(fileID,formatSpec,N,'Delimiter','|');

读取文件中的数值数据。

C_data0 = textscan(fileID,'%d %f %f %f')
C_data0=1×4 cell array
    {4x1 int32}    {4x1 double}    {4x1 double}    {4x1 double}

CollectOutput 的默认值是 0 (false),因此 textscan 以一个单独的数组返回每列数值数据。

将文件位置指示符设置为文件的开头。

frewind(fileID);

重新读取文件并将 CollectOutput 设置为 1 (true),将相同类的连续列收集到一个单独的数组中。您可以使用 repmat 函数指示 %f 转换设定符必须出现三次。当一种格式重复多次时,此方法很有用。

C_text = textscan(fileID,'%s',N,'Delimiter','|');
C_data1 = textscan(fileID,['%d',repmat('%f',[1,3])],'CollectOutput',1)
C_data1=1×2 cell array
    {4x1 int32}    {4x3 double}

测试分数(均为 double)被收集到一个单独的 4×3 数组中。

关闭文件。

fclose(fileID);

读取文本文件的第一列数据和最后一列数据。跳过文本列和整数数据列。

加载文件 names.txt 并在文本编辑器中预览其内容。屏幕截图如下所示。请注意,该文件包含两列带引号的文本,后跟一个整数列,最后一列为浮点数。

filename = 'names.txt';

读取该文件中的第一列数据和最后一列数据。使用转换设定符 %q 读取由双引号 (") 引起来的文本。%*q 跳过引用文本,%*d 跳过整数字段,而 %f 读取浮点数。使用 'Delimiter' 名称-值对组参数指定逗号分隔符。

fileID = fopen(filename,'r');
C = textscan(fileID,'%q %*q %*d %f','Delimiter',',');
fclose(fileID);

显示输出。textscan 返回元胞数组 C,其中删除了文本前后的双引号。

celldisp(C)
 
C{1}{1} =
 
Smith, J.
 
 
C{1}{2} =
 
Bates, G.
 
 
C{1}{3} =
 
Curie, M.
 
 
C{1}{4} =
 
Murray, G.
 
 
C{1}{5} =
 
Brown, K.
 
 
C{2} =
 
   71.1000
   69.3000
   64.1000
  133.0000
   64.9000

 

加载文件 german_dates.txt 并在文本编辑器中预览其内容。屏幕截图如下所示。请注意,第一列值包含德语的日期,第二列和第三列是数值。

filename = 'german_dates.txt';

打开文件。将与文件关联的字符编码方案指定为 fopen 的最后输入。

fileID = fopen(filename,'r','n','ISO-8859-15');

读取文件。使用 %{dd % MMMM yyyy}D 设定符指定文件中日期的格式。使用 DateLocale 名称-值对组参数指定日期的区域设置。

C = textscan(fileID,'%{dd MMMM yyyy}D %f %f',...
    'DateLocale','de_DE','Delimiter',',');
fclose(fileID);

查看 C 中第一个元胞的内容。日期以 MATLAB 使用的语言显示,具体取决于您的系统区域设置。

C{1}
ans = 3x1 datetime
   01 January 2014 
   01 February 2014
   01 March 2014   

使用 sprintf 转换数据中的非默认转义序列。

创建包含换页符 \f 的文本。随后,要使用 textscan 读取文本,请调用 sprintf 显式转换换页符。

lyric = sprintf('Blackbird\fsinging\fin\fthe\fdead\fof\fnight');
C = textscan(lyric,'%s','delimiter',sprintf('\f'));
C{1}
ans = 7x1 cell
    {'Blackbird'}
    {'singing'  }
    {'in'       }
    {'the'      }
    {'dead'     }
    {'of'       }
    {'night'    }

textscan 返回元胞数组 C

从开头以外的位置恢复扫描。

如果恢复文本扫描,textscan 每次都会从开头读取。要从任何其他位置恢复扫描,请在 textscan 的初始调用中使用双输出参数语法。

例如,创建一个名为 lyric 的字符向量。读取该字符向量的第一个词,然后恢复扫描。

lyric = 'Blackbird singing in the dead of night';
[firstword,pos] = textscan(lyric,'%9c',1);
lastpart = textscan(lyric(pos+1:end),'%s');

输入参数

全部折叠

已打开的文本文件的文件标识符,指定为数值。使用 textscan 读取文件之前,您必须使用 fopen 打开文件并获取 fileID

数据类型: double

数据字段的格式,指定为由一个或多个转换设定符组成的字符向量或字符串。textscan 在读取输入时,会尝试将数据与 formatSpec 中指定的格式进行匹配。如果 textscan 未能匹配数据字段,它将会停止读取并在出错前返回读取的所有字段。

转换设定符的数量确定输出数组 C 中元胞的数量。

数值字段

下表列出了可用于数值输入的转换设定符。

数值输入类型转换设定符输出类
有符号整数%dint32
%d8int8
%d16int16
%d32int32
%d64int64
无符号整数%uuint32
%u8uint8
%u16uint16
%u32uint32
%u64uint64
浮点数%fdouble
%f32single
%f64double
%ndouble
十六进制数、无符号整数%xuint64
%xu8uint8
%xu16uint16
%xu32uint32
%xu64uint64
十六进制数、有符号整数%xs8int8
%xs16int16
%xs32int32
%xs64int64
二进制数、无符号整数%buint64
%bu8uint8
%bu16uint16
%bu32uint32
%bu64uint64
二进制数、有符号整数%bs8int8
%bs16int16
%bs32int32
%bs64int64

非数值字段

下表列出了可用于包含非数值字符的输入的转换设定符。

非数值输入类型转换设定符详细信息
字符%c读取任何单个字符,包括分隔符。
文本数组%s读取为字符向量元胞数组。
%q

读取为字符向量元胞数组。如果文本以双引号 (") 开头,则忽略该前导引号及与其成对的后引号,该后引号是双引号的第二个实例。将转义双引号(例如 ""abc"")替换为单独双引号 ("abc")。%q 会忽略出现在后双引号之后的任何双引号。

示例:'%q''"Joe ""Lightning"" Smith, Jr."' 读作 'Joe "Lightning" Smith, Jr.'

日期时间%D

以与上面的 %q 相同的方式读取,然后转换为日期时间值。

%{fmt}D

以与上面的 %q 相同的方式读取,然后转换为日期时间值。fmt 描述输入文本的格式。fmt 输入是一个字母标识符字符向量,该字符向量为日期时间的 Format 属性的有效值。textscan 会将与此格式不匹配的文本转换为 NaT 值。

有关日期时间显示格式的详细信息,请参阅日期时间数组的 Format 属性。

示例:'%{dd-MMM-yyyy}D' 指定某个日期的格式,例如 '01-Jan-2014'

持续时间%T

以与上面的 %q 相同的方式读取,然后转换为持续时间值。

%{fmt}T

以与上面的 %q 相同的方式读取,然后转换为持续时间值。fmt 描述输入文本的格式。fmt 输入是一个字母标识符字符向量,该字符向量为持续时间的 Format 属性的有效值。textscan 会将与此格式不匹配的文本转换为 NaN 值。

有关持续时间显示格式的详细信息,请参阅持续时间数组的 format 属性。

示例:'%{hh:mm:ss}T' 指定持续时间的格式,例如 '10:30:15' 表示 10 小时 30 分钟 15 秒。

类别%C

以与 %q 相同的方式读取,然后转换为分类数组中的类别名称。textscan 会将 <undefined> 文本转换为输出分类数组中的未定义值。

模式匹配%[...]

将方括号中的字符读取为字符向量元胞数组,直到遇到第一个不匹配的字符。要在集合中包括 ],请首先指定它:%[]...]

示例:%[mus]'summer ' 读作 'summ'

%[^...]

排除方括号中的字符,直到读取到第一个匹配的字符。要排除 ],请首先指定它:%[^]...]

示例:%[^xrg]'summer ' 读作 'summe'

可选运算符

formatSpec 中的转换设定符可以包含按以下顺序显示的可选运算符(包含为了表达清晰而保留的空格):

In %*5.2f, * designates ignore field, 5 is the field width, .2 is the precision, and f is the conversion character.

可选运算符包括:

  • 要忽略的字段和字符

    textscan 按顺序读取文件中的所有字符,除非您要求它忽略特定字段或字段中的某一部分。

    在百分比字符 (%) 之后插入星号字符 (*),可跳过某个字段或字符字段中的某一部分。

    运算符

    采取的操作

    %*k

    跳过字段。k 是标识要跳过的字段的任何转换设定符。textscan 不会为任何此类字段创建输出元胞。

    示例:'%s %*s %s %s %*s %*s %s'(空白为可选项)将文本
    'Blackbird singing in the dead of night' 转换为四个输出元胞,即
    'Blackbird' 'in' 'the' 'night'

    '%*ns'

    跳过 n 个字符,其中 n 是小于或等于字段中字符数的一个整数。

    示例:'%*3s %s''abcdefg' 转换为 'defg'。如果分隔符为逗号,则同一分隔符将 'abcde,fghijkl' 转换为包含 'de';'ijkl' 的元胞数组。

    '%*nc'

    跳过 n 个字符,包括分隔符。

  • 字段宽度

    textscan 读取字段宽度或精度指定的字符数或位数,或者读到第一个分隔符,以先出现者为准。小数点、符号(+-)、指数字符以及数字指数中的数字计为字段宽度中的字符和数字。对于复数,字段宽度指的是实部和虚部的各自宽度。对于虚部,字段宽度包括 + 或 −,但不包括 ij。通过在转换设定符中的百分号 (%) 之后插入数字来指定字段宽度。

    示例:%5f'123.456' 读作 123.4

    示例:%5c'abcdefg' 读作 'abcde'

    当字段宽度操作符与单个字符 (%c) 一起使用时,textscan 也会读取分隔符、空白和行尾字符。
    示例:%7c 读取包括空白在内的 7 个字符,因此 'Day and night' 读作 'Day and'

  • 精度

    对于浮点数(%n%f%f32%f64),可以指定要读取的小数位数。

    示例:%7.2f'123.456' 读作 123.45

  • 要忽略的字面文本

    textscan 忽略追加到 formatSpec 转换设定符的文本。

    示例:Level%u8'Level1' 读作 1

    示例:%u8Step'2Step' 读作 2

数据类型: char | string

要应用 formatSpec 的次数,指定为正整数。

数据类型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

要读取的输入文本。

数据类型: char | string

名称-值参数

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

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

示例: C = textscan(fileID,formatSpec,'HeaderLines',3,'Delimiter',',') 跳过数据的前三行,然后读取其余数据,并将逗号视为分隔符。

名称不区分大小写。

确定数据串联的逻辑指示符,指定为由 'CollectOutput'true/false 组成的逗号分隔对组。如果为 true,则导入函数会将同一 MATLAB® 基础类的连续输出元胞串联为单个数组。

用于指定要忽略的文本的符号,指定为逗号分隔的对组,其中包含 'CommentStyle' 和一个字符向量、字符向量元胞数组、字符串或字符串数组。

例如,指定一个字符(如 '%')以忽略同一行上此符号后面的文本。指定一个包含两个字符向量的元胞数组(如 {'/*','*/'}),以忽略这些序列之间的任何文本。

MATLAB 仅检查位于每个字段开头而不是字段中的注释。

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

数据类型: char | string

用于读取日期的区域设置,指定为逗号分隔的对组,包含 'DateLocale'xx_YY 格式的字符向量,其中 xx 是用于指定语言的小写 ISO 639-1 双字母代码,YY 是用于指定国家/地区的大写 ISO 3166-1 alpha-2 代码。有关区域设置的常见值的列表,请参阅 datetime 函数的 Locale 名称-值对组参数。

使用 DateLocale 指定 textscan 在使用 %D 格式设定符将文本以日期形式读取时,应采用何种区域设置来解释月份和星期名称以及缩写。

示例: 'DateLocale','ja_JP'

字段分隔符,指定为由 'Delimiter' 以及一个字符向量或字符向量元胞数组组成的逗号分隔对组。在字符向量元胞数组中指定多个分隔符。

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

textscan 将重复的分隔符字符解释为多个分隔符,并向输出元胞返回一个空值。

在每一行数据中,默认字段分隔符是空白。空白可以是空格 (' ')、退格符 ('\b') 或制表符 ('\t') 的任意组合。如果您未指定分隔符,则:

  • 分隔符与空白字符相同。默认的空白字符为 ' ''\b''\t'。使用 'Whitespace' 名称-值对组参数指定替代的空白字符。

  • textscan 将重复的空白字符解释为单个分隔符。

当您将以下转义序列之一指定为分隔符时,textscan 将该序列转换成对应的控制字符:

\b退格符
\n换行符
\r回车符
\t制表符
\\反斜杠 (\)

数据类型: char | string

被分隔的文本文件中空数值字段的返回值,指定为由 'EmptyValue' 和一个标量组成的逗号分隔对组。

行尾字符,指定为由 'EndOfLine' 和一个字符向量或字符串组成的逗号分隔对组。该字符向量必须为 '\r\n',或须指定单个字符。常用的行尾字符是换行符 ('\n') 或回车符 ('\r')。如果您指定 '\r\n',则导入函数会将 \r\n 以及两者的组合 (\r\n) 视为行尾字符。

默认的行尾序列是 \n\r\r\n,具体取决于您的文件的内容。

如果文件最后一行的结尾有缺失值和行尾序列,则导入函数会对这些字段返回空值。这样可确保输出元胞数组 C 中的各个元胞的大小相同。

示例: 'EndOfLine',':'

数据类型: char | string

指数字符,指定为由 'ExpChars' 和一个字符向量或字符串组成的逗号分隔对组。默认的指数字符为 eEdD

数据类型: char | string

标题行数,指定为由 'HeaderLines' 和一个正整数组成的逗号分隔对组。textscan 会跳过标题行,包括当前行的剩余部分。

多分隔符处理,指定为由 'MultipleDelimsAsOne'true/false 组成的逗号分隔对组。如果为 true,则导入函数将连续分隔符当作一个分隔符处理。由空白分隔的重复分隔符也被当作一个分隔符处理。您还必须指定 Delimiter 选项。

示例: 'MultipleDelimsAsOne',1

textscan 未能读取或转换数据时的行为,指定为由 'ReturnOnError'true/false 组成的逗号分隔对组。如果是 true,则 textscan 终止,不产生错误,返回所有读取的字段。如果是 false,则 textscan 终止,产生错误,不返回输出元胞数组。

要作为空值处理的占位符文本,指定为逗号分隔的对组,其中包含 'TreatAsEmpty' 和一个字符向量、字符向量元胞数组、字符串或字符串数组。此选项仅适用于数值字段。

数据类型: char | string

空白字符,指定为由 'Whitespace' 和一个字符向量或字符串(包含一个或多个字符)组成的逗号分隔对组。textscan 将空格字符 char(32) 添加到任何指定的 Whitespace,除非 Whitespace 为空 ('') 并且 formatSpec 包含任何转换设定符。

当您将下面一个转义序列指定为任意空白字符时,textscan 会将该序列转换成对应的控制字符:

\b退格符
\n换行符
\r回车符
\t制表符
\\反斜杠 (\)

数据类型: char | string

文本的输出数据类型,指定为逗号分隔的对组,其中包含 'TextType''char''string'。如果您指定值 'char'textscan 将以字符向量元胞数组的形式返回文本。如果您指定值 'string'textscan 将以 string 类型的数组形式返回文本。

输出参数

全部折叠

文件或文本数据,以元胞数组形式返回。

对于 formatSpec 中的每个数值转换设定符,textscan 函数将一个 K×1 MATLAB 数值向量返回给输出元胞数组 C,其中 Ktextscan 查找与此设定符匹配的字段的次数。

对于 formatSpec 中的每个文本转换设定符(%s%q%[...]),textscan 函数都返回一个 K×1 字符向量元胞数组,其中 Ktextscan 查找与此设定符匹配的字段的次数。对于包含字段宽度操作符的每个字符转换,textscan 返回一个 K×M 字符数组,其中 M 是字段宽度。

对于 formatSpec 中的每个日期时间或分类转换设定符,textscan 函数将一个 K×1 日期时间或分类向量返回给输出元胞数组 C,其中 Ktextscan 查找与此设定符匹配的字段的次数。

扫描结束时在文件或字符向量中的位置,以 double 类的整数形式返回。对于文件,该值等同于调用 textscan 后运行 ftell(fileID) 所返回的值。对于字符向量,position 指示 textscan 读取了多少个字符。

算法

textscan 根据关于溢出、截断和使用 NaNInf-Inf 的 MATLAB 规则将数值字段转换为指定的输出类型。例如,MATLAB 将整数 NaN 表示为零。如果 textscan 发现空白字段与整数格式设定符(如 %d%u)相关联,则将空值作为零返回,而不是作为 NaN

在将数据匹配到文本转换设定符时,textscan 会一直读取到发现分隔符或行尾字符为止。在将数据匹配到数值转换设定符时,textscan 会一直读取到发现非数值字符为止。如果 textscan 无法再将数据匹配到特定的转换设定符,它会尝试将数据匹配到 formatSpec 中的下一个转换设定符。符号(+-)、指数字符和小数点视为数值字符。

In the number -12.345e+6, the - and + are signs. The 1, 2, 3, 4, 5, and 6 are digits. The period or dot is the decimal point. The e is the exponent character.

符号数字小数点数字指数字符符号数字
读取一个符号字符(如果存在)。读取一个或多个数字。读取一个小数点(如果存在)。如果存在小数点,则读取紧跟小数点后的一个或多个数字。读取一个指数字符(如果存在)。如果存在指数字符,则读取一个符号字符。如果存在指数字符,则读取该字符后面的一个或多个数字。

textscan 将任何复数作为一个整体导入到复数字段中,将实部和虚部转换为指定的数字类型(如 %d%f)。复数的有效形式如下:

±<real>±<imag>i|j

示例:5.7-3.1i

±<imag>i|j

示例:-7j

不要在复数中包含嵌入的空白。textscan 将嵌入的空白解释为字段分隔符。

扩展功能

版本历史记录

在 R2006a 之前推出

全部展开