RunMat
GitHub

View all functions

CategoryIo: Filetext

What does the fgets function do in MATLAB / RunMat?

fgets(fid) returns the next line from the text file associated with fid, preserving any newline characters that terminate the line. It mirrors MATLAB's behaviour for optional length limits, line-terminator reporting, and end-of-file handling so existing scripts work without modification.

How does the fgets function behave in MATLAB / RunMat?

  • tline = fgets(fid) reads from the current position to the next newline (including the newline) or to end-of-file when no terminator is found. The result is a character row vector with MATLAB's column-major semantics.
  • tline = fgets(fid, nchar) limits the read to at most nchar characters (rounded toward zero). The call stops early if a newline is encountered before the limit. When the newline appears beyond the limit, the delimiter is left unread for the next call.
  • [tline, ltout] = fgets(___) additionally returns the line terminators as a row vector of doubles. For Windows newlines (\r\n) the second output is [13 10], for Unix newlines (\n) it is 10, and it is empty when the line has no terminator.
  • When the file is empty or the file position indicator is already at end-of-file, tline (and ltout, if requested) return -1.
  • Lines are decoded using the text encoding recorded by fopen. UTF-8, US-ASCII, ISO-8859-1 (latin1), Windows-1252, Shift_JIS, and binary mode are recognised without additional user work.

fgets Function GPU Execution Behaviour

fgets is a host-only operation. File identifiers live in the host registry created by fopen, so arguments that arrive as GPU-resident scalars are gathered back to the CPU before the read occurs. The returned line and optional terminator vector are regular host values; no GPU residency is tracked.

Examples of using the fgets function in MATLAB / RunMat

Read the first line of a file

fname = tempname;
fid = fopen(fname, 'w');
fprintf(fid, 'RunMat\nSecond line\n');
fclose(fid);

fid = fopen(fname, 'r');
line = fgets(fid);
fclose(fid);
delete(fname);

double(line)

Expected output:

ans =
    82   117   110    77    97   116    10

Limit the number of characters returned

fname = tempname;
fid = fopen(fname, 'w');
fprintf(fid, 'Example line\n');
fclose(fid);

fid = fopen(fname, 'r');
snippet = fgets(fid, 5);
fclose(fid);
delete(fname);

snippet
double(snippet)

Expected output:

snippet =
    'Exam'
ans =
    69   120    97   109

Retrieve line terminators separately

fname = tempname;
fid = fopen(fname, 'w');
fprintf(fid, 'Windows line\r\n');
fclose(fid);

fid = fopen(fname, 'r');
[line, ltout] = fgets(fid);
fclose(fid);
delete(fname);

content = line(1:end-numel(ltout));
terminators = double(ltout);

content
terminators

Expected output:

content =
    'Windows line'
terminators =
    13    10

Handle lines without a trailing newline

fname = tempname;
fid = fopen(fname, 'w');
fprintf(fid, 'last line');
fclose(fid);

fid = fopen(fname, 'r');
[line1, lt1] = fgets(fid);
line2 = fgets(fid);
fclose(fid);
delete(fname);

line1
lt1
line2

Expected output:

line1 =
    'last line'
lt1 =
     []
line2 =
    -1

Detect end of file using the return value

fname = tempname;
fid = fopen(fname, 'w');
fprintf(fid, 'one\n');
fprintf(fid, 'two\n');
fclose(fid);

fid = fopen(fname, 'r');
tline = fgets(fid);
while tline ~= -1
    fprintf('> %s', tline);
    tline = fgets(fid);
end
fclose(fid);
delete(fname);

Expected output:

> one
> two

Read Latin-1 encoded text

fname = tempname;
fid = fopen(fname, 'w', 'n', 'latin1');
fprintf(fid, 'Español\n');
fclose(fid);

fid = fopen(fname, 'r', 'n', 'latin1');
line = fgets(fid);
fclose(fid);
delete(fname);

text = line(1:end-1);
codes = double(text);

text
codes

Expected output:

text =
    'Español'
codes =
    69   115   112    97   241   111   108

FAQ

What does fgets return at end-of-file?

When no characters can be read because the file position indicator is at end-of-file, fgets returns the numeric value -1. If you request two outputs, ltout is also -1 in this case.

Does fgets strip newline characters?

No. Unlike fgetl, fgets keeps any newline bytes in the returned character vector so you can distinguish empty lines from lines that end in a newline.

How do I interpret the second output ltout?

ltout contains the numeric codes for the terminators that ended the line. Use char(ltout) or double(ltout) to inspect them. On Windows you typically see [13 10], on Unix-like platforms 10, [] when the line has no terminator, and -1 when end-of-file is reached.

What happens if I specify an nchar limit?

RunMat reads at most nchar characters. If the newline characters appear before reaching the limit, they are included in the output. If the limit is reached first, the newline remains unread and ltout is empty.

Which encodings are supported?

fgets honours the encoding recorded by fopen. UTF-8, US-ASCII, Latin-1 (ISO-8859-1), Windows-1252, Shift_JIS, and binary mode are recognised. On most Unix-like systems the system encoding resolves to UTF-8; on Windows it defaults to Windows-1252.

How does fgets differ from fgetl?

fgetl removes newline characters, while fgets keeps them. Use fgetl when you want newline-free strings and fgets when you need to preserve the exact bytes that appear in the file.

Can I call fgets on files opened for writing only?

No. The file must be opened with read permission (for example 'r', 'r+', or 'w+'). Calling fgets on a write-only identifier raises an error.

See Also

fopen, fclose, feof, fread, fileread

Source & Feedback

  • Implementation: crates/runmat-runtime/src/builtins/io/filetext/fgets.rs
  • Found a bug? Open an issue with a minimal repro.