textread (MATLAB Function Reference)

Read formatted data from text file

Syntax

[A,B,C,...] = textread('filename','format')
[A,B,C,...] = textread('filename','format',N)
[...] = textread(...,'param','value',...)

Description

[A,B,C,...] = textread('filename','format')

reads data from the file 'filename' into the variables A,B,C, and so on, using the specified format, until the entire file is read. textread is useful for reading text files with a known format. Both fixed and free format files can be handled.

textread matches and converts groups of characters from the input. Each input field is defined as a string of non-whitespace characters that extends to the next whitespace or delimiter character, or to the maximum field width. Repeated delimiter characters are significant, while repeated whitespace characters are treated as one.

The format string determines the number and types of return arguments. The number of return arguments is the number of items in the format string. The format string supports a subset of the conversion specifiers and conventions of the C language FSCANF function. Values for the format string are listed in the table below. Whitespace characters in the format string are ignored.


format	Action	Output
Literals (ordinary characters)	Ignore the matching characters. For example, in a file that has `Dept` followed by a number (for department number), to skip the `Dept` and read only the number, use `'Dept'` in the `format` string.	None
`%d`	Read a signed integer value.	Double array
`%u`	Read an integer value.	Double array
`%f`	Read a floating point value.	Double array
`%s`	Read a whitespace-separated string.	Cell array of strings
`%q`	Read a string, which could be in double quotes.	Cell array of strings. Does not include the double quotes.
`%c`	Read characters, including white space.	Character array
`%[...]`	Read the longest string containing characters specified in the brackets.	Cell array of strings
`%[^...]`	Read the longest non-empty string containing characters that are not specified in the brackets.	Cell array of strings
`%*...` `instead of %`	Ignore the matching characters specified by `*.`	No output
`%w...` `instead of %`	Read field width specified by `w`. The `%f` format supports `%w.pf`, where `w` is the field width and `p` is the precision.

[A,B,C,...] = textread('filename','format',N)

reads the data, reusing the format string N times, where N is an integer greater than zero. If N is smaller than zero, textread reads the entire file.

[...] = textread(...,'param','value',...)

customizes textread using param/value pairs, as listed in the table below.


param	value	Action
`whitespace`	`\* where * can be:`	Treats vector of characters, `*`, as whitespace. Default is `\b\r\n\t`.
	`b` `f` `n` `r` `t` `\\` `\'' or ''` `%%`	Backspace Form feed New line Carriage return Horizontal tab Backslash Single quotation mark Percent sign
`delimiter`	Delimiter character	Specifies delimiter character. Default is none.
`expchars`	Exponent characters	Default is `eEdD`.
`bufsize`	positive integer	Specifies the maximum string length, in bytes. Default is `4095`.
`headerlines`	positive integer	Ignores the specified number of lines at the beginning of the file.
`commentstyle`	`matlab`	Ignores characters after `%`
`commentstyle`	`shell`	Ignores characters after `#`.
`commentstyle`	`c`	Ignores characters between `/` and `/`.
`commentstyle`	`c++`	Ignores characters after `//`.

Examples

Example 1 - Read All Fields in Free Format File Using %

The first line of mydata.dat is

Sally    Type1 12.34 45 Yes

Read the first line of the file as a free format file using the % format.

[names,types,x,y,answer] = textread('mydata.dat','%s %s %f ...
    %d %s',1)

returns

names = 
    'Sally'
types = 
    'Type1'
x =
  12.34000000000000
y =
    45
answer = 
    'Yes'

Example 2 - Read as Fixed Format File, Ignoring the Floating Point Value

The first line of mydata.dat is

Sally    Type1 12.34 45 Yes

Read the first line of the file as a fixed format file, ignoring the floating point value.

[names,types,y,answer] = textread('mydata.dat','%9c %5s %*f ... 
...
    %2d %3s',1)

returns

names =
Sally    
types = 
    'Type1'
y =
    45
answer = 
    'Yes'

%*f in the format string causes textread to ignore the floating point value, in this case, 12.34.

Example 3 - Read Using Literal to Ignore Matching Characters

The first line of mydata.dat is

Sally    Type1 12.34 45 Yes

Read the first line of the file, ignoring the characters Type in the second field.

[names,typenum,x,y,answer] = textread('mydata.dat','%s Type%d %f 
%d %s',1)

returns

names = 
    'Sally'
typenum =
     1
x =
  12.34000000000000
y =
    45
answer = 
    'Yes'

Type%d in the format string causes the characters Type in the second field to be ignored, while the rest of the second field is read as a signed integer, in this case, 1.

Example 4 - Read M-file into a Cell Array of Strings

Read the file fft.m into cell array of strings.

file = textread('fft.m','%s','delimiter','\n','whitespace','');