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