RunMat
GitHub

View all functions

CategoryIo: Filetext

fileread — Read the entire contents of a text file into a 1-by-N character vector.

fileread(filename) loads the complete contents of a text file into memory and returns a row vector of characters that mirrors MATLAB's behaviour. The builtin preserves all bytes, including newlines and extended ASCII characters, so downstream code can parse, split, or convert the text as needed.

How does the fileread function behave in MATLAB / RunMat?

  • Accepts paths provided as character vectors or string scalars. String arrays must contain exactly one element.
  • Supports an optional encoding argument: fileread(filename, encoding) or fileread(filename, 'Encoding', encoding). Recognised values include auto (default), utf-8, ascii, latin1, and raw.
  • Resolves relative paths with respect to the current working directory of the RunMat process, just like MATLAB.
  • Returns a 1×N character array. Empty files yield a 1×0 character vector.
  • Leaves line endings untouched (\r, \n, or \r\n) so scripts can inspect original formatting.
  • When auto decoding detects invalid UTF-8 sequences, RunMat maps each byte to the corresponding extended-ASCII code point so that callers can recover the raw data.
  • Throws a descriptive error when the file cannot be opened or read.

GPU behavior

fileread performs synchronous host I/O and never dispatches GPU work. If the provided file name lives on the GPU (for example, produced by a GPU array that was gathered lazily), RunMat gathers that scalar first. File contents are returned as an ordinary character array that resides on the CPU. Providers do not need to implement any hooks for this builtin.

Examples of using fileread in MATLAB / RunMat

Read Entire File Into A Character Vector

text = fileread("LICENSE.md")

Expected output:

text =
    Character vector containing the full license text

Read A File Using A Relative Path

text = fileread("data/config.json")

Expected output:

text =
    Returns the JSON file contents as a character vector

Preserve Extended ASCII Bytes

bytes = fileread("fixtures/high_ascii.txt");
double_values = double(bytes)

Expected output:

double_values =
    65    66    67

Convert File Contents To A String Scalar

raw = fileread("README.md");
doc = string(raw)

Expected output:

doc =
    "RunMat docs"

Read A File With UTF-8 Decoding Explicitly

text = fileread("data/report.txt", 'Encoding', 'utf-8')

Expected output:

text =
    Character vector decoded using UTF-8.

Handle Missing Files With Try/Catch

try
    fileread("missing.txt");
catch err
    disp(err.message);
end

Expected output:

fileread: unable to read 'missing.txt': readFile: not found

FAQ

What does fileread return?

It returns a 1×N character vector containing every byte from the file. Convert it to a string with string(...) when you prefer string scalars.

Does fileread change line endings?

No. The builtin preserves whatever newline sequence the file uses so downstream tools can handle formatting explicitly.

Can fileread read binary data?

While designed for text, fileread will happily return any bytes. The result is a character vector whose numeric codes match the file's bytes.

How are encodings handled?

The default auto mode attempts UTF-8 decoding and, if the data is not valid UTF-8, falls back to mapping each byte to its extended-ASCII code point (latin1). Provide an explicit encoding such as 'utf-8', 'latin1', 'ascii', or 'raw' to control the conversion. Explicit encodings raise descriptive errors when the bytes are incompatible with the requested format.

Can I force raw byte behaviour?

Yes. Specify 'raw' (or 'bytes') as the encoding argument to receive a character vector whose code points equal the file's bytes.

How do relative paths resolve?

Relative paths are evaluated against the current working directory of the RunMat process. Use pwd or cd to control where fileread looks.

See also

fopen, fread, string, strlength

Source & Feedback