Main Content

textread

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

collapse all in page

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.

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.

example

Examples

collapse all

Open Live Script

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'}
Open Live Script

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'}
Open Live Script

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
Open Live Script

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 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'

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

Version History

Introduced before R2006a

collapse all

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 RecommendedRecommended
[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)

See Also

| | |