fscanf

Purpose

Read formatted data from file.

Synopsis

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

Description

[A,count] = fscanf(fid,'format') reads all the data from the file specified by file identifier fid, converts it according to the specified format string, and returns it in matrix A. fid is an integer file identifier obtained from fopen.

[A,count] = fscanf(fid,'format',size) returns count, the number of elements successfully read. size can be

-------------------------------------------------------------
n      Read n elements into a column vector.                    
inf    Read to the end of the file, resulting in a column vec   
       tor containing the same number of elements as are in     
       the file.                                                
[m,n]  Read enough elements to fill an m-by-n matrix, filling   
       the matrix in column order. n can be inf, but not m.     
-------------------------------------------------------------
The format string specifies the format of the data to be read. When MATLAB reads the 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 matrix in column order. If a partial match occurs, only the matching data is written to the matrix, and the read operation stops.

The format string can consist 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. Legal conversion characters are

---------------------------------------------------
%d           decimal numbers                         
%e, %f, %g   floating-point numbers                  
%s           a series of non-white-space characters  
---------------------------------------------------
Between the % and the conversion character (d, e, f, g, or s), you can add one or more of the following characters:

----------------------------------------------------------------------------
an asterisk (*)  Skip over the matched value, if the value is matched         
                 but not stored in the output matrix.                         
a digit string   Maximum field width.                                         
a letter         The size of the receiving object; for example, h for short   
                 as in %hd for a short integer, or l for long as in %ld for   
                 a long integer or %lg for a double floating-point num        
                 ber.                                                         
----------------------------------------------------------------------------
For more information about format strings, refer to the scanf() and fscanf() routines in a C language reference manual.

fscanf differs from its C language namesakes scanf() and fscanf() in an important respect - it is vectorized in order to return a matrix argument. The format string is recycled through the file until an end-of-file is reached or the amount of data specified by size is read in.

Examples

The example in fprintf generates an ASCII text file called exp.txt that looks like:

    0.00    1.00000000
    0.10    1.10517092
    ...
    1.00    2.71828183
Read this ASCII file back into a two-column MATLAB matrix:

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

See Also

fclose, ferror, fopen, fprintf, fread, fseek, ftell, fwrite, sscanf

(c) Copyright 1994 by The MathWorks, Inc.