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.

Syntax

[Var1,Var2,...,VarN] = textread(filename,format)

[Var1,Var2,...,VarN] = textread(filename,format,N)

[Var1,Var2,...,VarN] = textread(___,Name,Value)

Description

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

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

[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

Read All Fields in Free Format File

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 = 1×1 cell array
    {'09/12/2005'}

level = 1×1 cell array
    {'Level1'}

x = 
12.3400

y = 
45

answer = 1×1 cell array
    {'1.23e10'}

Read Using Literal to Ignore Matching Characters

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 = 1×1 cell array
    {'09/12/2005'}

level = 
1

x = 
12.3400

y = 
45

answer = 1×1 cell array
    {'1.23e10'}

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)

data = 2×6

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

Read File into a Cell Array of Character Vectors

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

file = textread('badpoem.txt','%s','delimiter','\n','whitespace','')

file = 4×1 cell
    {'Oranges and lemons,'    }
    {'Pineapples and tea.'    }
    {'Orangutans and monkeys,'}
    {'Dragonflys or fleas.'   }

Input Arguments

filename — File name

character vector | string scalar

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

format — Format

character vector | 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.

N — Number of times to read the data

positive integer

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 pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'WriteMode','append'

bufsize — Maximum length of the character vector

4095 (default) | positive integer

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

commentstyle — Ignore characters with respect to associated symbols

'matlab' | 'shell' | 'c' | 'c++'

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

delimiter — Delimiters between elements

one or more characters

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.

emptyvalue — Value given to empty cells

0 (default) | scalar double

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

endofline — Character that denotes the end of a line

determined from file (default) | single character | '\r\n'

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

exchars — Exponent characters

'eEdD' (default) | exponent characters

Designate exponent characters, specified as exponent characters.

headerlines — Number of header lines

positive integer

Number of header lines, specified as a positive integer.

whitespace — Vector of characters to be treated as whitespace character

' \b\t' (default) | ' ' | \b | \n | \r | \t

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

Version History

Introduced before R2006a

R2012b: textread is not recommended

textread is not recommended. Use textscan instead. There are no plans to remove textread.

Use the textscan function to read formatted data from a text file or string. Workflows using textscan have several advantages over using the textread function.

• Unlike textread, the output provided by textscan is a cell array.

• The file pointer is maintained between calls to textscan allowing you to read data in portions.

• The textscan workflow supports reading from remote locations.

• The error messages produced by textscan provide clear guidance on how to adjust your syntax and workflow.

This table shows some typical usages of textread and how to update your code to use textscan instead.

Not Recommended	Recommended
[date,level,x,y,answer] = textread('scan1.dat',... '%s %s %f %d %s',1)	filename = 'scan1.dat'; fileID = fopen(filename); C = textscan(fileID,'%s %s %f %d %s'); fclose(fileID); celldisp(C)
data = textread('data.csv','','delimiter',',',... 'emptyvalue',NaN)	filename = 'data.csv'; fileID = fopen(filename); C = textscan(fileID,'%f %f %f %f %u8 %f', ... 'Delimiter',',','EmptyValue',NaN); fclose(fileID); celldisp(C)