filewrite — Write text or raw bytes with RunMat's native file-writing extension.

filewrite(filename, data) is a RunMat-native extension that writes text or raw byte content to a file and returns the number of bytes written. MATLAB does not provide a filewrite builtin; MATLAB-compatible mode therefore rejects this API before gathering data or modifying the filesystem. Enable RunMat extensions to use it.

Syntax

count = filewrite(filename, data)
count = filewrite(filename, data, encoding)
count = filewrite(filename, data, "Encoding", encoding)
count = filewrite(filename, data, ..., "WriteMode", mode)

Inputs

Returns

Errors

How filewrite works

• 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. All eight integer classes (int8, int16, int32, int64, uint8, uint16, uint32, and uint64) are read exactly and must lie in the range 0–255; double inputs use the existing integral-byte validation in that range, and 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.

Does RunMat run filewrite on the GPU?

filewrite performs synchronous host file I/O. Provider-resident numeric data is gathered before writing. No GPU kernels are launched and providers do not need to implement specialised hooks for this RunMat-native 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

Using filewrite with coding agents

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

FAQ

Related Io functions

Open-source implementation

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

• View the source for filewrite 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.

Getting started · Benchmarks · Pricing