RunMat
GitHub

fileread — Read full text files into character vectors in MATLAB and RunMat.

fileread(filename) loads an entire text file into memory and returns a 1-by-N character row vector. Newlines and byte content are preserved in the returned text, with path and encoding behavior matching MATLAB semantics.

Syntax

text = fileread(filename)
text = fileread(filename, encoding)
text = fileread(filename, "Encoding", encoding)

Inputs

NameTypeRequiredDefaultDescription
filenameAnyYes—Path to a readable file.
encodingStringScalarNo"auto"Encoding label (for example 'utf-8', 'latin1', 'ascii', 'raw').
namePropertyNameNo"Encoding"Name of supported option; currently only 'Encoding'.
valuePropertyValueNo"auto"Option value for the provided option name.

Returns

NameTypeDescription
textAnyFile contents as a 1-by-N character vector.

Errors

IdentifierWhenMessage
RunMat:fileread:InvalidInputFilename or argument cardinality/type constraints are violated.fileread: invalid input arguments
RunMat:fileread:InvalidOptionEncoding option syntax or value is invalid.fileread: invalid option configuration
RunMat:fileread:DecodeFailedRequested decoding of bytes fails (for example UTF-8 or ASCII mismatch).fileread: unable to decode file contents

How fileread works

  • 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.

Does RunMat run fileread on the GPU?

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

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

Using fileread with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how fileread changes the result.

Run a small fileread example, explain the result, then change one input and compare the output.

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.

Filetext

fclose · feof · fgetl · fgets · filewrite · fopen · fprintf · fread · frewind · fwrite

Repl Fs

addpath · cd · copyfile · delete · dir · exist · fullfile · genpath · getenv · ls · mkdir · movefile · path · pwd · rmdir · rmpath · run · savepath · setenv · tempdir · tempname · uigetfile · uiputfile

Io

clc · disp · format · input

Mat

load · save

Archive

unzip

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how fileread is executed, line by line, in Rust.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.

  • RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
  • Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing

Download RunMat

Download RunMat for full performance, or use RunMat in your browser for zero setup.

Download RunMatTry in your browser