fscanf - Read data from a text file

Syntax

A = fscanf(fileID, format) A = fscanf(fileID, format, sizeA) [A, count] = fscanf(...)

Description

A = fscanf(fileID, format) reads and converts data from a text file into array A in column order. To convert, fscanf uses the format and the encoding scheme associated with the file. To set the encoding scheme, use fopen. The fscanf function reapplies the format throughout the entire file, and positions the file pointer at the end-of-file marker. If fscanf cannot match the format to the data, it reads only the portion that matches into A and stops processing.

A = fscanf(fileID, format, sizeA) reads sizeA elements into A, and positions the file pointer after the last element read. sizeA can be an integer, or can have the form [m,n].

[A, count] = fscanf(...) returns the number of elements that fscanf successfully reads.

Inputs

fileID

Integer file identifier obtained from fopen.

format

String enclosed in single quotation marks that describes each type of element (field). Includes one or more of the following specifiers.

Field Type	Specifier	Details
Integer, signed	`%d`	Base 10
Integer, signed	`%i`	Base determined from the values. Defaults to base 10. If initial digits are `0x` or `0X`, it is base 16. If initial digit is `0`, it is base 8.
Integer, unsigned	`%u`	Base 10
	`%o`	Base 8 (octal)
	`%x`	Base 16 (hexadecimal)
Floating-point number	`%f`	Floating-point fields can contain any of the following (not case sensitive): `Inf`, `-Inf`, `NaN`, or `-NaN`.
	`%e`
	`%g`
Character string	`%s`	Read series of characters, until find white space.
	`%c`	Read any single character, including white space. (To read multiple characters, specify field length.)
	`%[...]`	Read only characters in the brackets, until the first nonmatching character or white space.

Optionally:

To skip fields, insert an asterisk (*) after the percent sign (%). For example, to skip integers, specify %*d.
To specify the maximum width of a field, insert a number. For example, %10c reads exactly 10 characters at a time, including white space.
To skip a specific set of characters, insert the literal characters in the format. For example, to read only the floating-point number from 'pi=3.14159', specify a format of 'pi=%f'.

sizeA

Dimensions of the output array A. Specify in one of the following forms:

`inf`	Read to the end of the file. (default)
`n`	Read at most `n` elements.
`[m,n]`	Read at most `mn` elements in column order. `n`* can be `inf`, but `m` cannot.

When the format includes %s, A can contain more than n columns. n refers to elements, not characters.

Outputs

A

An array. If the format includes:

Only numeric specifiers, A is numeric, of class double. If sizeA is inf or n, then A is a column vector. If the input contains fewer than sizeA elements, MATLAB pads A with zeros.
Only character or string specifiers (%c or %s), A is a character array. If sizeA is inf or n, A is a row vector. If the input contains fewer than sizeA characters, MATLAB pads A with char(0).
A combination of numeric and character specifiers, A is numeric, of class double. MATLAB converts each character to its numeric equivalent. This conversion occurs even when the format explicitly skips all numeric values (for example, a format of '%*d %s').

If MATLAB cannot match the input to the format, and the format contains both numeric and character specifiers, A can be numeric or character. The class of A depends on the values MATLAB reads before processing stops.

count

The number of elements fscanf reads into A.

Examples

Read the contents of a file. fscanf reuses the format throughout the file, so you do not need a control loop:

% Create a file with an exponential table
x = 0:.1:1;
y = [x; exp(x)];

fid = fopen('exp.txt', 'w');
fprintf(fid, '%6.2f %12.8f\n', y);
fclose(fid);

% Read the data, filling A in column order
% First line of the file:
%    0.00    1.00000000

fid = fopen('exp.txt');
A = fscanf(fid, '%g %g', [2 inf]);
fclose(fid);

% Transpose so that A matches
% the orientation of the file
A = A';

Skip specific characters in a file, and return only numeric values:

% Create a file with temperatures
tempstr = '78°F 72°F 64°F 66°F 49°F';

fid = fopen('temperature.dat', 'w+');
fprintf(fid, '%s', tempstr);

% Return to the beginning of the file
frewind(fid);

% Read the numbers in the file, skipping the units
% num_temps is a numeric column vector

degrees = char(176);
num_temps = fscanf(fid, ['%d' degrees 'F']);

fclose(fid);