Main Content

textread

(Not Recommended) Read data from text file; write to multiple outputs

textread is not recommended. Use textscan instead. For more information see Compatibility Considerations.

Description

example

[Var1,Var2,...,VarN] = textread(filename,format) reads data from the file filename into the variables [Var1,Var2,...,VarN] using the specified format, until the entire file is read. textread is useful for reading text files with a known format. textread handles both fixed and free format files.

textread matches and converts groups of characters from the input. Each input field is defined as a group 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.

example

[Var1,Var2,...,VarN] = textread(filename,format,N) reads the data, reusing the specified format N times. If N is less than zero, textread reads the entire file.

example

[Var1,Var2,...,VarN] = textread(___,Name,Value) specifies options using one or more Name,Value pair arguments, in addition to any of the input arguments in the previous syntaxes.

Examples

collapse all

The first row of the sample data, 'scan1.dat', is

09/12/2005 {'Level1'} 12.34 45 1.23e+10 Inf NaN {'Yes'} 5.1+3i

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

[date,level,x,y,answer] = textread('scan1.dat','%s %s %f %d %s',1)
date = 1x1 cell array
    {'09/12/2005'}

level = 1x1 cell array
    {'Level1'}

x = 12.3400
y = 45
answer = 1x1 cell array
    {'1.23e10'}

The first row of the sample data, 'scan1.dat', is

09/12/2005 {'Level1'} 12.34 45 1.23e+10 Inf NaN {'Yes'} 5.1+3i

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

[date,level,x,y,answer] = textread('scan1.dat','%s Level%d %f %d %s',1)
date = 1x1 cell array
    {'09/12/2005'}

level = 1
x = 12.3400
y = 45
answer = 1x1 cell array
    {'1.23e10'}

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)
data = 2×6

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

Read the file fft.m into a cell array of character vectors.

file = textread('badpoem.txt','%s','delimiter','\n','whitespace','')
file = 4x1 cell
    {'Oranges and lemons,'    }
    {'Pineapples and tea.'    }
    {'Orangutans and monkeys,'}
    {'Dragonflys or fleas.'   }

Input Arguments

collapse all

File name, specified as a character vector or string scalar.

Format, specified as a character vector or a string scalar. This argument determines the number and types of return arguments. The number of return arguments is the number of items indicated by the contents of format. format supports a subset of the conversion specifiers and conventions of the C language fscanf routine. Values for format are listed in the table below. Whitespace characters in format 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 specifier.

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 or delimiter-separated text.

Cell array of character vectors

%q

Read double quoted text, ignoring the quotes.

Cell array of character vectors

%c

Read characters, including white space.

Character array

%[...]

Read the longest group of characters containing characters specified in the brackets.

Cell array of character vectors

%[^...]

Read the longest nonempty group of characters containing characters that are not specified in the brackets.

Cell array of character vectors

%*...
instead of %

Ignore the matching characters specified by *.

None

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

 

Number of times to read the data, specified as a positive integer. If N is less than zero, textread reads the entire file.

Name-Value Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'WriteMode','append'

Maximum length of the character vector in bytes, specified as a positive integer.

Ignores characters with respect to associated symbols, specified as 'matlab', 'shell', 'c', or 'c++'.

Value

Behavior

'matlab'

Ignores characters after %.

'shell'

Ignores characters after #.

'c'

Ignores characters between /* and */.

'c++'

Ignores characters after //.

Delimiters between elements, specified as one or more characters. When textread reads a consecutive series of delimiter values, it treats each as a separate delimiter.

Value given to empty cells when reading delimited files, specified as a scalar double.

Character that denotes the end of a line, specified as a single character or '\r\n'.

Designate exponent characters, specified as exponent characters.

Number of header lines, specified as a positive integer.

Value given to empty cells when reading delimited files, specified as a scalar double. When textread reads a consecutive series of whitespace values, it treats them as one white space.

You can preserve leading and trailing spaces in the text, using whitespace.

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

Value

Behavior

' '

Space

\b

Backspace

\n

Newline

\r

Carriage return

\t

Horizontal tab

Compatibility Considerations

expand all

Not recommended starting in R2012b

Introduced before R2006a