filewrite — Write text or raw bytes with RunMat's native file-writing extension.
filewrite(filename, data) writes text or raw bytes and returns the number of bytes written. It is a RunMat-native extension, not a MATLAB builtin; MATLAB-compatible mode rejects it before gathering data or changing the filesystem.
Syntax
count = filewrite(filename, data)
count = filewrite(filename, data, encoding)
count = filewrite(filename, data, "Encoding", encoding)
count = filewrite(filename, data, ..., "WriteMode", mode)Inputs
filename- Type
Any- Required
- Yes
- Description
- Path to target file.
data- Type
Any- Required
- Yes
- Description
- Text or uint8-compatible data to write.
encoding- Type
StringScalar- Required
- No
- Default
"auto"- Description
- Positional encoding label.
name- Type
PropertyName- Required
- Variadic
- Description
- Option name: 'Encoding' or 'WriteMode'.
value- Type
PropertyValue- Required
- Variadic
- Description
- Option value associated with option name.
Returns
count- Type
NumericScalar- Description
- Number of bytes written.
Errors
RunMat:filewrite:InvalidInput- When
- Filename/data argument constraints are violated.
- Message
filewrite: invalid input arguments
RunMat:filewrite:InvalidOption- When
- Name/value options are malformed or unsupported.
- Message
filewrite: invalid option configuration
RunMat:filewrite:InvalidData- When
- Input data cannot be converted to writable bytes.
- Message
filewrite: unsupported data payload
Inputs and bytes
The filename is a one-row character vector, string scalar, or one-element string array. Character vectors, string scalars, and string arrays are text data; string-array elements are joined in column-major order with newline separators. Numeric arrays and logical arrays are raw bytes, with logical false/true mapping to 0/1. All eight integer classes use exact integer storage and each value must be in 0..255; double values must pass integral-byte validation.
The default write mode truncates the target. 'WriteMode','append' adds bytes without inserting a newline. A missing parent directory is not created. The returned count is a host double scalar measuring bytes written, not characters.
A positional encoding or 'Encoding',value pair accepts auto, utf-8, ascii, latin1, and raw (with documented aliases). Auto and utf-8 encode text as UTF-8; ascii and latin1 reject characters outside their code pages. Numeric data already represents bytes, so encoding has no conversion effect except ASCII validation.
Host execution
File I/O executes through the installed host filesystem. Provider-resident real numeric data is gathered through its owning provider before payload conversion; there is no filewrite GPU kernel or fusion path. Filename and option controls must already be host text, and known-invalid forms fail before data download or filesystem effects.
The current writer prepares the complete payload in host memory before opening the destination. A resident value without its owning acceleration provider raises a gather-provider error; no GPU kernel is launched. Permission, missing-directory, write, and flush failures retain their underlying I/O cause. Browser use requires a real installed filesystem service.
Examples
Write text to a new file
bytes = filewrite('notes.txt', 'Hello, RunMat!');
bytesExpected output:
bytes = 14Append without overwriting
filewrite('log.txt', sprintf('First line\n'));
bytes = filewrite('log.txt', sprintf('Second line\n'), 'WriteMode', 'append');
bytesExpected output:
bytes = 12Select a text encoding
bytes = filewrite('latin1.txt', ['E' 's' 'p' 'a' char(241) 'a'], 'Encoding', 'latin1');
bytesExpected output:
bytes = 6Write raw numeric bytes
payload = [1 2 3 255];
bytes = filewrite('data.bin', payload, 'Encoding', 'raw');
bytesExpected output:
bytes = 4Export a string array
lines = ["alpha", "beta", "gamma"];
bytes = filewrite('items.txt', lines);
bytesExpected output:
bytes = 16Reject non-ASCII characters in ASCII mode
filewrite('ascii.txt', ['c' 'a' 'f' char(233)], 'Encoding', 'ascii');Expected output:
filewrite: failed to encode payload: character 'é' (U+00E9) cannot be encoded as ASCIIUsing filewrite with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how filewrite changes the result.
Run a small filewrite example, explain the result, then change one input and compare the output.
FAQ
What does filewrite return?⌄
A double scalar counting bytes written. The output may be omitted when it is not needed.
How are string arrays written?⌄
Their elements are written in column-major order, separated by newlines. This is RunMat-native behavior.
Is a newline added automatically?⌄
Not for ordinary text or append mode. Supply an explicit newline; string-array elements are the exception because they are joined with newline separators.
How can I write binary data?⌄
Supply byte-valued numeric or logical data. The raw encoding makes the byte intent explicit, though the default also writes numeric bytes directly.
What happens if the file cannot be opened?⌄
A file I/O error reports the underlying cause, such as permission denial or a missing directory.
Does filewrite create directories?⌄
No. Create the parent directory first, for example with mkdir.
Related Io functions
Filetext
fclose · feof · fgetl · fgets · fileread · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fileattrib · fileparts · filesep · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · memmapfile.subsasgn · memmapfile.subsref · 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 · getvaropts · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · setvaropts · setvartype · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Data
commit · data.copy · data.create · data.delete · data.exists · data.export · data.import · data.inspect · data.list · data.move · data.open · DataArray.chunk_shape · DataArray.codec · DataArray.dtype · DataArray.fill · DataArray.name · DataArray.rank · DataArray.read · DataArray.resize · DataArray.shape · DataArray.write · Dataset.array · Dataset.arrays · Dataset.attrs · Dataset.begin · Dataset.get_attr · Dataset.has_array · Dataset.id · Dataset.path · Dataset.refresh · Dataset.set_attr · Dataset.set_attrs · Dataset.snapshot · Dataset.version · DataTransaction.abort · DataTransaction.commit · DataTransaction.create_array · DataTransaction.delete_array · DataTransaction.fill · DataTransaction.id · DataTransaction.resize · DataTransaction.set_attr · DataTransaction.set_attrs · DataTransaction.status · DataTransaction.write
Import
Json
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.