writematrix — Write numeric or string matrices to delimited text files.
writematrix(A, filename) serializes a numeric or string matrix to a delimited text file. Native integer matrices retain their exact decimal values.
Syntax
writematrix(data, filename)
writematrix(data, filename, name, optionValue)
writematrix(data, filename, nameValuePairs...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
data | Any | Yes | — | Numeric or string matrix to write. |
filename | StringScalar | Yes | — | Output file path. |
name | StringScalar | Yes | — | Option name. |
optionValue | Any | Yes | — | Value for the preceding option name. |
nameValuePairs... | Any | Variadic | — | Name-value option pairs. |
Errors
| Identifier | When | Message |
|---|---|---|
| — | Filename argument is missing or name-value options are malformed. | writematrix: invalid argument configuration |
| — | Filename is not a valid scalar path string. | writematrix: invalid filename input |
| — | A provided option value is invalid. | writematrix: invalid option value |
| — | Input data cannot be converted into a supported writematrix matrix form. | writematrix: invalid input data |
| — | Input data has unsupported dimensionality. | writematrix: input must be 2-D |
| — | The destination file cannot be opened or written. | writematrix: file write failed |
How writematrix works
- Accepts real numeric, logical, or string arrays with up to two dimensions (trailing singleton dimensions are ignored). Heterogeneous data requires
writecellinstead. - Default delimiters follow MATLAB: comma for
.csv, tab for.tsv, whitespace for.txtand.dat, and comma for other extensions. Specify'Delimiter', valueto override. 'WriteMode'supports'overwrite'(default) and'append'. Overwrite truncates existing files; append writes new rows to the end without inserting extra delimiters.'QuoteStrings'accepts'minimal'(default),'all', or'none'. Minimal quoting protects fields that contain the delimiter, a quote, or a line break.- RunMat mode also accepts logical and numeric zero/one aliases for
'QuoteStrings', the text-format options'DecimalSeparator'and'LineEnding', and a bytes-written output. 'FileType'accepts'delimitedtext'or'text'. Spreadsheet output ('spreadsheet') is not yet available and triggers a descriptive error consistent with MATLAB's messaging.- Spreadsheet output is not yet implemented. Sparse input is rejected.
Does RunMat run writematrix on the GPU?
The write executes on the host. Automatic residency is gathered through the owning provider, while explicit device intent is compatibility-gated before provider or file access.
GPU memory and residency
writematrix is a host file-I/O sink. Automatically resident values gather transparently before formatting; explicit gpuArray input requires RunMat mode.
Examples
Save a numeric matrix to a CSV file
A = [1 2 3; 4 5 6];
writematrix(A, "results.csv")Export data with a custom semicolon delimiter
A = [1 2 3; 4 5 6];
writematrix(A, "results.dat", 'Delimiter', ';')Append additional rows to an existing report
writematrix([7 8 9], "report.txt");
writematrix([10 11 12], "report.txt", 'WriteMode', 'append')Write string data without quoting
names = ["Alice" "Bob" "Charlie"];
writematrix(names, "names.csv", 'QuoteStrings', 'none')Use RunMat text-format options
vals = [12.34; 56.78];
writematrix(vals, "eu.csv", 'DecimalSeparator', ',', 'LineEnding', 'unix')Capture the RunMat bytes-written output
bytes = writematrix(uint64([1 2 3]), "values.csv")Expected output:
% Requires RunMat language extensions.Using writematrix with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how writematrix changes the result.
Run a small writematrix example, explain the result, then change one input and compare the output.
FAQ
Which data types does writematrix support?⌄
Real numeric, logical, and string arrays up to two dimensions. For heterogenous content (mixed numbers and text) use writecell or writetable.
How are empty matrices handled?⌄
Zero-row or zero-column inputs produce either an empty file or blank line endings per MATLAB's behaviour. The file is still created or truncated according to 'WriteMode'.
Can I write OTA spreadsheet formats like .xlsx?⌄
Not yet. Passing 'FileType','spreadsheet' raises a descriptive error. Use MATLAB's table-based workflows or export delimited text instead.
How are embedded quotes in text fields escaped?⌄
With 'minimal' or 'all', embedded double quotes are doubled. With 'none', text is written verbatim.
What happens if I choose ',' as both delimiter and decimal separator?⌄
RunMat mode honours the request without modification, even though the output may be ambiguous. Choose a different delimiter when using the DecimalSeparator extension.
Does writematrix change the working directory?⌄
No. Relative paths are resolved against the current RunMat working directory, and only the target file is touched.
How do I include header rows or variable names?⌄
writematrix focuses on numeric and string matrices. Use writetable for named variables.
Related Io functions
Tabular
arrayDatastore · csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · fileDatastore · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · spreadsheetImportOptions · writecell · writetable · writetimetable · xlsread · xlswrite
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
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
Related guides
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how writematrix is executed, line by line, in Rust.
- View the source for writematrix 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.