fileread — Read a full text file into a character vector.
fileread(filename) loads an entire text file into memory and returns a 1-by-N character row vector. The documented filename and Encoding roles are textual, so numeric and integer inputs are inapplicable. RunMat currently supports local filesystem paths and a bounded encoding set; MATLAB search-path, URL, remote-filesystem, home-expansion, and broader encoding behavior are not yet fully implemented.
Syntax
text = fileread(filename)
text = fileread(filename, encoding)
text = fileread(filename, "Encoding", encoding)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
filename | Any | Yes | — | Path to a readable file. |
encoding | StringScalar | No | "auto" | Encoding label (for example 'utf-8', 'latin1', 'ascii', 'raw'). |
name | PropertyName | No | "Encoding" | Name of supported option; currently only 'Encoding'. |
value | PropertyValue | No | "auto" | Option value for the provided option name. |
Returns
| Name | Type | Description |
|---|---|---|
text | Any | File contents as a 1-by-N character vector. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:fileread:InvalidInput | Filename or argument cardinality/type constraints are violated. | fileread: invalid input arguments |
RunMat:fileread:InvalidOption | Encoding option syntax or value is invalid. | fileread: invalid option configuration |
RunMat:fileread:DecodeFailed | Requested decoding of bytes fails (for example UTF-8 or ASCII mismatch). | fileread: unable to decode file contents |
RunMat:fileread:IoFailure | Filesystem read operation fails. | fileread: file read failed |
| — | Internal runtime control-flow or conversion fails. | fileread: internal error |
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)orfileread(filename, 'Encoding', encoding). Recognised values includeauto(default),utf-8,ascii,latin1, andraw. - Resolves relative paths with respect to the current working directory of the RunMat process. Bare-name MATLAB search-path lookup is not yet implemented.
- Returns a
1×Ncharacter array. Empty files yield a1×0character vector. - Leaves line endings untouched (
\r,\n, or\r\n) so scripts can inspect original formatting. - When
autodecoding 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 host I/O and never dispatches GPU work. Provider-resident inputs are rejected before provider access, and file contents are returned as an ordinary host character array.
Examples
Read Entire File Into A Character Vector
text = fileread("LICENSE.md")Expected output:
text =
Character vector containing the full license textRead A File Using A Relative Path
text = fileread("data/config.json")Expected output:
text =
Returns the JSON file contents as a character vectorPreserve Extended ASCII Bytes
bytes = fileread("fixtures/high_ascii.txt");
double_values = double(bytes)Expected output:
double_values =
65 66 67Convert 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);
endExpected output:
fileread: unable to read 'missing.txt': readFile: not foundUsing 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 decoded file text. 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?⌄
The RunMat-only raw encoding alias maps each byte to one character code. The MATLAB-compatible contract is text-oriented.
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.
Related Io functions
Filetext
fclose · feof · fgetl · fgets · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fileattrib · fileparts · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · mkdir · movefile · open · opentoline · path · pathsep · pcode · pwd · readstruct · rehash · restoredefaultpath · rmdir · rmpath · run · savepath · setenv · setpref · system · tempdir · tempname · uigetdir · uigetfile · uiputfile · unsetenv · userpath · what · winqueryreg · xmlread · xmlwrite
Tabular
arrayDatastore · csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · fileDatastore · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Import
Json
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how fileread is executed, line by line, in Rust.
- View the source for fileread in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
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.