MATLAB Function Reference

fscanf - Read formatted data from file

Syntax

A = fscanf(fid, format)
[A,count] = fscanf(fid, format, size)

Description

A = fscanf(fid, format) reads data from the file specified by fid, converts it according to the specified format string, and returns it in matrix A. Argument fid is an integer file identifier obtained from fopen. format is a string specifying the format of the data to be read. See "Remarks" for details.

[A,count] = fscanf(fid, format, size) reads the amount of data specified by size, converts it according to the specified format string, and returns it along with a count of values successfully read. size is an argument that determines how much data is read. Valid options are

Characteristics of the output matrix A depend on the values read from the file and on the size argument. If fscanf reads only numbers, and if size is not of the form [m,n], matrix A is a column vector of numbers. If fscanf reads only characters or strings, and if size is not of the form [m,n], matrix A is a row vector of characters. See the Remarks section for more information.

fscanf differs from its C language namesake fscanf() in an important respect — it is vectorized to return a matrix argument. The format string is cycled through the file until the first of these conditions occurs:

• The format string fails to match the data in the file

• The amount of data specified by size is read

• The end of the file is reached

Remarks

When the MATLAB^® software reads a specified file, it attempts to match the data in the file to the format string. If a match occurs, the data is written into the output matrix. If a partial match occurs, only the matching data is written to the matrix, and the read operation stops.

The format string consists of ordinary characters and/or conversion specifications. Conversion specifications indicate the type of data to be matched and involve the character %, optional width fields, and conversion characters, organized as shown below.

Add one or more of these characters between the % and the conversion character:

Valid conversion characters are

Format specifiers %e, %f, and %g accept the text 'inf', '-inf', 'nan', and '-nan'. This text is not case sensitive. The fscanf function converts these to the numeric representation of Inf, -Inf, NaN, and -NaN.

Use %c to read space characters or %s to skip all white space. MATLAB skips over any ordinary characters that are used in the format specifier (see Example 2 below).

MATLAB reads characters using the encoding scheme associated with the file. See fopen for more information. If the format string contains ordinary characters, MATLAB matches each of those characters with a character read from the file after converting both to the MATLAB internal representation of characters.

For more information about format strings, refer to the scanf() and fscanf() routines in a C language reference manual.

Output Characteristics: Only Numeric Values Read

Format characters that cause fscanf to read numbers from the file are %d, %e, %f, %g, %i, %o, %u, and %x. When fscanf reads only numbers from the file, the elements of the output matrix A are numbers.

When there is no size argument or the size argument is inf, fscanf reads to the end of the file. The output matrix is a column vector with one element for each number read from the input.

When the size argument is a scalar n, fscanf reads at most n numbers from the file. The output matrix is a column vector with one element for each number read from the input.

When the size argument is a matrix [m,n], fscanf reads at most (m*n) numbers from the file. The output matrix contains at most m rows and n columns. fscanf fills the output matrix in column order, using as many columns as it needs to contain all the numbers read from the input. Any unfilled elements in the final column contain zeros.

Output Characteristics: Only Character Values Read

The format characters that cause fscanf to read characters and strings from the file are %c and %s. When fscanf reads only characters and strings from the file, the elements of the output matrix A are characters. When fscanf reads a string from the input, the output matrix includes one element for each character in the string.

When there is no size argument or the size argument is inf, fscanf reads to the end of the file. The output matrix is a row vector with one element for each character read from the input.

When the size argument is a scalar n, fscanf reads at most n character or string values from the file. The output matrix is a row vector with one element for each character read from the input. When string values are read from the input, the output matrix can contain more than n columns.

When the size argument is a matrix [m,n], fscanf reads at most (m*n) character or string values from the file. The output matrix contains at most m rows. fscanf fills the output matrix in column order, using as many columns as it needs to contain all the characters read from the input. When string values are read from the input, the output matrix can contain more than n columns. Any unfilled elements in the final column contain char(0).

Output Characteristics: Both Numeric and Character Values Read

When fscanf reads a combination of numbers and either characters or strings from the file, the elements of the output matrix A are numbers. This is true even when a format specifier such as '%*d %s' tells MATLAB to ignore numbers in the input string and output only characters or strings. When fscanf reads a string from the input, the output matrix includes one element for each character in the string. All characters are converted to their numeric equivalents in the output matrix.

When there is no size argument or the size argument is inf, fscanf reads to the end of the file. The output matrix is a column vector with one element for each character read from the input.

When the size argument is a scalar n, fscanf reads at most n number, character, or string values from the file. The output matrix contains at most n rows. fscanf fills the output matrix in column order, using as many columns as it needs to represent all the numbers and characters read from the input. When string values are read from the input, the output matrix can contain more than one column. Any unfilled elements in the final column contain zeros.

When the size argument is a matrix [m,n], fscanf reads at most (m*n) number, character, or string values from the file. The output matrix contains at most m rows. fscanf fills the output matrix in column order, using as many columns as it needs to represent all the numbers and characters read from the input. When string values are read from the input, the output matrix can contain more than n columns. Any unfilled elements in the final column contain zeros.

Note   This section applies only when fscanf actually reads a combination of numbers and either characters or strings from the file. Even if the format string has both format characters that would result in numbers (such as %d) and format characters that would result in characters or strings (such as %s), fscanf might actually read only numbers or only characters or strings. If fscanf reads only numbers, see Output Characteristics: Only Numeric Values Read. If fscanf reads only characters or strings, see Output Characteristics: Only Character Values Read.

Examples

Example 1

An example in fprintf generates a text file called exp.txt that looks like this:

0.00    1.00000000
0.10    1.10517092
...
1.00    2.71828183

Read this file back into a two-column MATLAB matrix:

fid = fopen('exp.txt', 'r');
a = fscanf(fid, '%g %g', [2 inf])    % It has two rows now.
a = a';
fclose(fid)

Example 2

Start with a file temp.dat that contains temperature readings:

78°F 72°F 64°F 66°F 49°F

Open the file using fopen and read it with fscanf. If you include ordinary characters (such as the degree (°) and Farrenheit (F) symbols used here) in the conversion string, fscanf skips over those characters when reading the string:

fid = fopen('temps.dat', 'r');

degrees = char(176)
degrees =
   °
fscanf(fid, ['%d' degrees 'F'])
ans =
    78
    72
    64
    66
    49

See Also

fgetl, fgets, fread, fprintf, fscanf, input, sscanf, textread

frewind

fscanf (serial)