fscanf

Read data from text file

Syntax

A = fscanf(fileID,formatSpec)

A = fscanf(fileID,formatSpec,sizeA)

[A,count] = fscanf(___)

Description

A = fscanf(fileID,formatSpec) reads data from an open text file into column vector A and interprets values in the file according to the format specified by formatSpec. 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 formatSpec to the data, it reads only the portion that matches and stops processing.

The text file is indicated by the file identifier, fileID. Use fopen to open the file, specify the character encoding, and obtain the fileID value. When you finish reading, close the file by calling fclose(fileID).

A = fscanf(fileID,formatSpec,sizeA) reads file data into an array, A, with dimensions, sizeA, and positions the file pointer after the last value read. fscanf populates A in column order. sizeA must be a positive integer or have the form [m n], where m and n are positive integers.

[A,count] = fscanf(___) additionally returns the number of fields that fscanf reads into A. For numeric data, this is the number of values read. You can use this syntax with any of the input arguments of the previous syntaxes.

Examples

Read File Contents into Column Vector

Create a sample text file that contains floating-point numbers.

x = 100*rand(8,1);
fileID = fopen('nums1.txt','w');
fprintf(fileID,'%4.4f\n',x);
fclose(fileID);

View the contents of the file.

type nums1.txt

81.4724
90.5792
12.6987
91.3376
63.2359
9.7540
27.8498
54.6882

Open the file for reading, and obtain the file identifier, fileID.

fileID = fopen('nums1.txt','r');

Define the format of the data to read. Use '%f' to specify floating-point numbers.

formatSpec = '%f';

Read the file data, filling output array, A, in column order. fscanf reapplies the format, formatSpec, throughout the file.

A = fscanf(fileID,formatSpec)

A = 8×1

   81.4724
   90.5792
   12.6987
   91.3376
   63.2359
    9.7540
   27.8498
   54.6882

A is a column vector containing data from the file.

Close the file.

fclose(fileID);

Read File Contents into Array

Create a sample text file that contains integers and floating-point numbers.

x = 1:1:5;
y = [x;rand(1,5)];
fileID = fopen('nums2.txt','w');
fprintf(fileID,'%d %4.4f\n',y);
fclose(fileID);

View the contents of the file.

type nums2.txt

1 0.8147
2 0.9058
3 0.1270
4 0.9134
5 0.6324

Open the file for reading, and obtain the file identifier, fileID.

fileID = fopen('nums2.txt','r');

Define the format of the data to read and the shape of the output array.

formatSpec = '%d %f';
sizeA = [2 Inf];

Read the file data, filling output array, A, in column order. fscanf reuses the format, formatSpec, throughout the file.

A = fscanf(fileID,formatSpec,sizeA)

A = 2×5

    1.0000    2.0000    3.0000    4.0000    5.0000
    0.8147    0.9058    0.1270    0.9134    0.6324

fclose(fileID);

Transpose the array so that A matches the orientation of the data in the file.

A = A'

A = 5×2

    1.0000    0.8147
    2.0000    0.9058
    3.0000    0.1270
    4.0000    0.9134
    5.0000    0.6324

Skip Specific Characters in File

Skip specific characters in a sample file, and return only numeric data.

Create a sample text file containing temperature values.

str = '78°C 72°C 64°C 66°C 49°C';
fileID = fopen('temperature.dat','w');
fprintf(fileID,'%s',str);
fclose(fileID);

Read the numbers in the file, skipping the text, °C. Also return the number of values that fscanf reads. The extended ASCII code 176 represents the degree sign.

fileID = fopen('temperature.dat','r');
degrees = char(176);
[A,count] = fscanf(fileID, ['%d' degrees 'C'])
fclose(fileID);

A =

    78
    72
    64
    66
    49


count =

     5

A is a vector containing the numeric values in the file. count indicates that fscanf read five values.

Input Arguments

fileID — File identifier

integer

File identifier of an open text file, specified as an integer. Before reading a file with fscanf, you must use fopen to open the file and obtain its identifier fileID.

Data Types: double

formatSpec — Format of data fields

character vector | string scalar

Format of the data fields in the file, specified as a character vector or string scalar of one or more conversion specifiers. When fscanf reads a file, it attempts to match the data to the format specified by formatSpec.

Numeric Fields

This table lists available conversion specifiers for numeric inputs. fscanf converts values to their decimal (base 10) representation.

Numeric Field Type	Conversion Specifier	Details
Integer, signed	%d	Base 10
	%i	The values in the file determine the base: The default is base 10. If the initial digits are 0x or 0X, then the values are hexadecimal (base 16). If the initial digit is 0, then values are octal (base 8).
	%ld or %li	64-bit values, base 10, 8, or 16
Integer, unsigned	%u	Base 10
	%o	Base 8 (octal)
	%x	Base 16 (hexadecimal)
	%lu, %lo, %lx	64-bit values, base 10, 8, or 16
Floating-point number	%f	Floating-point fields can contain any of the following (not case sensitive): Inf, -Inf, NaN, or -NaN.
	%e
	%g

Character Fields

This table lists available conversion specifiers for character inputs.

Character Field Type	Conversion Specifier	Description
Character vector or string scalar	%s	Read all characters excluding white spaces.
	%c	Read any single character, including white space. To read multiple characters at a time, specify field width.
Pattern-matching	%[...]	Read only characters in the brackets up to the first nonmatching character or white space. Example: %[mus] reads 'summer ' as 'summ'.

If formatSpec contains a combination of numeric and character specifiers, then fscanf converts each character to its numeric equivalent. This conversion occurs even when the format explicitly skips all numeric values (for example, formatSpec is '%*d %s').

Optional Operators

• Fields and Characters to Ignore

  fscanf reads all numeric values and characters in your file in sequence, unless you tell it to ignore a particular field or a portion of a field. To skip fields, insert an asterisk (*) after the percent sign (%). For example, to skip integers, specify %*d.

• Field Width

  To specify the maximum number of digits or text characters to read at a time, insert a number after the percent character. For example, %10c reads up to 10 characters at a time, including white space. %4f reads up to 4 digits at a time, including the decimal point.

• Literal Text to Ignore

  fscanf ignores specified text appended to the formatSpec conversion specifier.

  Example: Level%u reads 'Level1' as 1.

  Example: %uStep reads '2Step' as 2.

sizeA — Dimensions of output array

Inf (default) | integer | two-element row vector

Dimensions of the output array, A, specified as Inf, an integer, or a two-element row vector.

Form of the sizeA Input	Description
Inf	Read to the end of the file. For numeric data, the output, A, is a column vector. For text data, A is a character vector.
n	Read at most n numeric values or character fields. For numeric data, the output, A, is a column vector. For text data, A, is a character vector.
[m,n]	Read at most m*n numeric values or character fields. n can be Inf, but m cannot. The output, A, is m-by-n, filled in column order.

Output Arguments

A — File data

column vector | matrix | character vector | character array

File data, returned as a column vector, matrix, character vector or character array. The class and size of A depend on the formatSpec input:

• If formatSpec contains only numeric specifiers, then A is numeric. If you specify the sizeA argument, then A is a matrix of the specified size. Otherwise, A is a column vector. If the input contains fewer than sizeA values, then fscanf pads A with zeros.

  • If formatSpec contains only 64-bit signed integer specifiers, then A is of class int64.

  • If formatSpec contains only 64-bit unsigned integer specifiers, then A is of class uint64.

  • Otherwise, A is of class double.

• If formatSpec contains only character or text specifiers (%c or %s), then A is a character array. If you specify sizeA and the input contains fewer characters, then fscanf pads A with char(0).

• If formatSpec contains a combination of numeric and character specifiers, then A is numeric, of class double, and fscanf converts each text characters to its numeric equivalent. This occurs even when formatSpec explicitly skips all numeric fields (for example, formatSpec is '%*d %s').

• If MATLAB^® cannot match the file data to formatSpec, then A can be numeric or a character array. The class of A depends on the values that fscanf reads before it stops processing.

count — Number of characters read

scalar

Number of characters read, returned as a scalar value.

Tips

• Format specifiers for the reading functions sscanf and fscanf differ from the formats for the writing functions sprintf and fprintf. The reading functions do not support a precision field. The width field specifies a minimum for writing but a maximum for reading.

Algorithms

MATLAB reads characters using the encoding scheme associated with the file. You specify the encoding when you open the file using the fopen function.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• For MEX code generation, the code generator treats fscanf as an extrinsic function. See Use MATLAB Engine to Execute a Function Call in Generated Code (MATLAB Coder).

• The input argument formatSpec must be a constant.

• The %s and %[...] conversion specifiers are not supported.

• If you turn off dynamic memory allocation, you must provide the input argument sizeA and it must be a constant.

• In certain cases, the behavior of the generated code might differ from MATLAB. In such cases, the behavior of the generated code matches that of fscanf in the C language. These are some examples:

  • In the generated code, if fscanf reads a null byte, the returned values might be truncated.

  • If you read an integer value x into an integer format for which intmax is smaller than x, the MATLAB output saturates at intmax. In the generated code, this situation causes an overflow.

  • If you use the formatting specifier %c to specify a field width that is greater than the number of characters available in the input file fileID, MATLAB returns a string shorter than the specified length that contains only the available characters. The generated code returns a string of the specified length, but the contents of the returned string can vary depending on the C/C++ compiler you use. In some cases, the returned string contains the input string padded with null characters (char(0)). In other cases, the returned string contains only null characters.

  • In certain cases, after fscanf reads from a file, the location of the file pointer might be different in MATLAB and the generated code. For example, suppose that the file myFile.txt contains the character vector '1+2I'. You execute these commands:

    fid = fopen('myFile.txt','r');
    tmp = fscanf(fid, '%f')

    tmp =
    
         1
         2

    Use ftell to determine the current location of the position pointer in the file myFile.txt.

    ftell(fid)

    ans =
    
         3

    In MATLAB, after fscanf executes, the file pointer is positioned after the third character '2'. In the generated code, after fscanf executes, the file pointer is positioned at the end-of-file marker.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced before R2006a

R2024b: Read data over HTTP and HTTPS using low-level file functions

You can read data from primary online sources by performing low-level file read operations over an internet URL.

R2022b: Use function in thread-based environments

This function supports thread-based environments.