fgets

Read line from file, keeping newline characters

Syntax

tline = fgets(fileID)

tline = fgets(fileID,nchar)

[tline,ltout] = fgets(___)

Description

tline = fgets(fileID) reads the next line of the specified file, including the newline characters.

tline = fgets(fileID,nchar) returns up to nchar characters of the next line.

[tline,ltout] = fgets(___) also returns the line terminators, if any, in ltout.

Examples

Read File One Line at a Time

Read a single line from a file, first excluding newline characters, and then including them. Use the following file.

To read the first line from the file badpoem.txt, use fopen to open the file. Then read the first line using fgetl, which excludes the newline character.

fid = fopen('badpoem.txt');
line_ex = fgetl(fid)  % read line excluding newline character

line_ex = 
'Oranges and lemons,'

To reread the same line from the file, first reset the read position indicator back to the beginning of the file.

frewind(fid);

Use the fgets function to read the first line from the file badpoem.txt, which reads the line including the newline character.

line_in = fgets(fid) % read line including newline character

line_in = 
    'Oranges and lemons,
     '

Compare the output by examining the lengths of the lines returned by the fgetl and fgets functions.

length(line_ex)

ans = 
19

length(line_in)

ans = 
20

fgetl returns an output that displays in one line, while fgets returns an output that includes the newline character and, therefore, displays it in two lines.

line_ex

line_ex = 
'Oranges and lemons,'

line_in 

line_in = 
    'Oranges and lemons,
     '

Close the file.

fclose(fid);

Input Arguments

fileID — File identifier

integer

File identifier of an open file, specified as an integer. Before using fgets to read a line from the file, you must use fopen to open the file and obtain its identifier fileID.

Data Types: double

nchar — Number of characters

integer

Number of characters to read from the next line, specified as an integer. fgets returns at most nchar characters of the next line. If the number of characters specified by nchar includes characters beyond the newline character or the end-of-file marker, then fgets does not return any characters beyond the new line character or the end-of-file marker.

Data Types: double

Output Arguments

tline — Next line in file

character vector | numeric scalar

Next line in file, returned as a character vector or numeric scalar.

• If the file is nonempty, then fgets returns tline as a character vector.

• If the file is empty and contains only the end-of-file marker, then fgets returns tline as a numeric value -1.

ltout — Line terminators

integer

Line terminators, returned as an integer.

The integers from 0 to 65535 correspond to Unicode^®characters. You can convert integers to their corresponding Unicode representations using the char function.

Tips

• tline does not include any characters after the newline characters or the end-of-file marker.

• fgets reads characters using the encoding scheme associated with the file. To specify the encoding scheme, use fopen.

• To read lines from a file while removing newline characters, use fgetl.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• If the function fgets does not read content from the file, then the generated code reports either an error or returns an empty value instead of returning -1.

• If the function fgets reads a null byte, the returned values might be truncated.

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.