filewrite — Write text or raw bytes to a file with optional encoding and write-mode control.

filewrite(filename, data) writes text or raw byte content to a file, returning the number of bytes written. The builtin honours MATLAB semantics for overwrite versus append behaviour and supports the same encoding keywords that fileread recognises.

How filewrite works in RunMat

• Accepts file names supplied as character vectors, string scalars, or scalar string arrays.
• Accepts data supplied as character vectors, string scalars, string arrays, or numeric arrays of bytes (uint8/double values in the range 0–255). Logical arrays map to bytes 0 and 1.
• By default the file is truncated (overwrite mode). Pass 'WriteMode','append' to add to an existing file.
• Encoding is optional. Provide either a positional encoding argument or the 'Encoding', value keyword pair. Supported encodings mirror fileread: auto (default), utf-8, ascii, latin1, and raw.
• When writing text data with filewrite and Encoding set to ascii or latin1, an error is raised if any characters fall outside the permitted code page.
• When writing raw numeric bytes, encoding is ignored except to validate ASCII requests.
• Returns the number of bytes written as a double scalar. Ignoring the output behaves like MATLAB (data is still written).

How filewrite runs on the GPU

filewrite performs synchronous host file I/O. If either the path or data reside on the GPU (for example through lazy residency), RunMat gathers those values before performing the write. No GPU kernels are launched and providers do not need to implement specialised hooks for this builtin.

Examples

Write Text To A New File

bytes = filewrite("notes.txt", "Hello, RunMat!")

Expected output:

bytes = 14

Append Text Without Overwriting

filewrite("log.txt", "First line\n");
bytes = filewrite("log.txt", "Second line\n", 'WriteMode', 'append')

Expected output:

bytes = 13

Specify A Particular Encoding

bytes = filewrite("latin1.txt", ['E' 's' 'p' 'a' char(241) 'a'], 'Encoding', 'latin1')

Expected output:

bytes = 6

Write Raw Bytes From A Numeric Array

payload = [1 2 3 255];
bytes = filewrite("data.bin", payload, 'Encoding', 'raw')

Expected output:

bytes = 4

Export A String Array As Newline-Separated Text

lines = ["alpha", "beta", "gamma"];
bytes = filewrite("items.txt", lines)

Expected output:

bytes = 16

Handle Invalid ASCII Characters

try
    filewrite("ascii.txt", ['c' 'a' 'f' char(233)], 'Encoding', 'ascii');
catch err
    disp(err.message);
end

Expected output:

filewrite: character 'é' (U+00E9) cannot be encoded as ASCII

FAQ

What does filewrite return?

It returns the number of bytes written as a double scalar. Omit the output argument when you do not need this information.

How are string arrays written?

Each element of the string array is written sequentially (column-major order), separated by newline characters. This mirrors MATLAB’s filewrite behaviour and matches what most users expect when exporting string arrays.

Does filewrite add a newline automatically?

No. Provide explicit newline characters (\n) when you want line breaks. Appending mode ('WriteMode','append') does not insert separators automatically.

How can I write binary data?

Provide a numeric array with values in the range 0–255 (for example uint8). Use 'Encoding','raw' (or rely on the default) to bypass text encoding.

What happens if the file cannot be opened?

filewrite throws a descriptive error containing the system message (for example, permissions or directory-not-found issues).

Does the builtin create directories?

No. The parent directory must already exist. Use mkdir before calling filewrite if you need to create folders.

Related functions to explore

These functions work well alongside filewrite. Each page has runnable examples you can try in the browser.

fileread, fwrite, fprintf, string, fclose, feof, fgets, fopen, fread, frewind

Open-source implementation

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

• View filewrite.rs on GitHub
• Learn how the 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 — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing