RunMat
GitHub

View all functions

CategoryIo: Filetext

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 does the filewrite function behave in MATLAB / 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).

GPU behavior

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 of using filewrite in MATLAB / RunMat

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.

See also

fileread, fwrite, fprintf, string

Source & Feedback