fscanf
Read data from text file
Description
A = fscanf(
reads
data from an open text file into column vector fileID
,formatSpec
)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(
reads
file data into an array, fileID
,formatSpec
,sizeA
)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.
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 |
| Base 10 |
| The values in the file determine the base:
| |
| 64-bit values, base 10, 8, or 16 | |
Integer, unsigned |
| Base 10 |
| Base 8 (octal) | |
| Base 16 (hexadecimal) | |
| 64-bit values, base 10, 8, or 16 | |
Floating-point number | | Floating-point fields can contain
any of the following (not case sensitive): |
| ||
|
Character Fields
This table lists available conversion specifiers for character inputs.
Character Field Type | Conversion Specifier | Description |
---|---|---|
Character vector or string scalar |
| Read all characters excluding white spaces. |
| Read any single character, including white space. | |
Pattern-matching |
| Read only characters in the brackets up to the first nonmatching character or white space. Example: |
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 theformatSpec
conversion specifier.Example:
Level%u
reads'Level1'
as1
.Example:
%uStep
reads'2Step'
as2
.
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. |
| 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. |
[ | Read at most 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, thenA
is numeric. If you specify thesizeA
argument, thenA
is a matrix of the specified size. Otherwise,A
is a column vector. If the input contains fewer thansizeA
values, thenfscanf
padsA
with zeros.If
formatSpec
contains only 64-bit signed integer specifiers, thenA
is of classint64
.If
formatSpec
contains only 64-bit unsigned integer specifiers, thenA
is of classuint64
.Otherwise,
A
is of classdouble
.
If
formatSpec
contains only character or text specifiers (%c
or%s
), thenA
is a character array. If you specifysizeA
and the input contains fewer characters, thenfscanf
padsA
withchar(0)
.If
formatSpec
contains a combination of numeric and character specifiers, thenA
is numeric, of classdouble
, andfscanf
converts each text characters to its numeric equivalent. This occurs even whenformatSpec
explicitly skips all numeric fields (for example,formatSpec
is'%*d %s'
).If MATLAB® cannot match the file data to
formatSpec
, thenA
can be numeric or a character array. The class ofA
depends on the values thatfscanf
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
andfscanf
differ from the formats for the writing functionssprintf
andfprintf
. 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 whichintmax
is smaller thanx
, the MATLAB output saturates atintmax
. 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 filefileID
, 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 filemyFile.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 filemyFile.txt
.ftell(fid)
ans = 3
In MATLAB, after
fscanf
executes, the file pointer is positioned after the third character'2'
. In the generated code, afterfscanf
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 R2006aR2024b: 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.
Commande MATLAB
Vous avez cliqué sur un lien qui correspond à cette commande MATLAB :
Pour exécuter la commande, saisissez-la dans la fenêtre de commande de MATLAB. Les navigateurs web ne supportent pas les commandes MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)