textread

Read data from text file; write to multiple outputs

    Note:   textread is not recommended. Use textscan instead.

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. The filename and format inputs are strings, each enclosed in single quotes. textread is useful for reading text files with a known format. textread handles both fixed and free format files.

    Note   When reading large text files, reading from a specific point in a file, or reading file data into a cell array rather than multiple outputs, you might prefer to use the textscan function.

textread matches and converts groups of characters from the input. Each input field is defined as a string of non-white-space characters that extends to the next white-space or delimiter character, or to the maximum field width. Repeated delimiter characters are significant, while repeated white-space 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 routine. Values for the format string are listed in the table below. White-space 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 white-space or delimiter-separated string.

Cell array of strings

%q

Read a double quoted string, ignoring the quotes.

Cell array of strings

%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 nonempty 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

bufsize

Positive integer

Specifies the maximum string length, in bytes. Default is 4095.

commentstylematlab

Ignores characters after %.

commentstyleshell

Ignores characters after #.

commentstylec

Ignores characters between /* and */.

commentstylec++

Ignores characters after //.

delimiter

One or more characters

Act as delimiters between elements. Default is none.

emptyvalue

Scalar double

Value given to empty cells when reading delimited files. Default is 0.

endofline

Single character or '\r\n'

Character that denotes the end of a line.

Default is determined from file

expchars

Exponent characters

Default is eEdD.

headerlines

Positive integer

Ignores the specified number of lines at the beginning of the file.

whitespace

Any from the list below:

Treats vector of characters as white space. Default is ' \b\t'.

' '
\b
\n
\r
\t

Space
Backspace
Newline
Carriage return
Horizontal tab

    Note   When textread reads a consecutive series of whitespace values, it treats them as one white space. When it reads a consecutive series of delimiter values, it treats each as a separate delimiter.

Examples

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

The first line of mydata.dat is

Sally    Level1 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 = 
    'Level1'
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    Level1 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 %6s %*f %2d %3s', 1)

returns

names =
Sally    
types = 
    'Level1'
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 — Specify Value to Fill Empty Cells

For files with empty cells, use the emptyvalue parameter. Suppose the file data.csv contains:

1,2,3,4,,6
7,8,9,,11,12

Read the file using NaN to fill any empty cells:

data = textread('data.csv', '', 'delimiter', ',', ... 
                'emptyvalue', NaN);

Example 5 — Read 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', '');

More About

expand all

Tips

If you want to preserve leading and trailing spaces in a string, use the whitespace parameter as shown here:

textread('myfile.txt', '%s', 'whitespace', '')
ans = 
    '   An  example      of preserving    spaces      '

See Also

| |

Was this topic helpful?