dlmwrite — Write numeric matrices to delimiter-separated text files in MATLAB and RunMat.
dlmwrite(filename, M) writes numeric matrix data to plain-text files using configurable delimiters. Precision, line-ending, and offset options follow MATLAB and RunMat legacy semantics.
Syntax
bytesWritten = dlmwrite(filename, M)
bytesWritten = dlmwrite(filename, M, delimiter, row, col)
bytesWritten = dlmwrite(filename, M, name, optionValue)
bytesWritten = dlmwrite(filename, M, args...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
filename | StringScalar | Yes | — | Output file path. |
M | Any | Yes | — | Numeric/logical matrix to write. |
delimiter | StringScalar | Yes | "," | Delimiter token. |
row | IntegerScalar | Yes | 0 | Row offset before writing matrix rows. |
col | IntegerScalar | Yes | 0 | Column offset before writing matrix columns. |
name | StringScalar | Yes | — | Option name. |
optionValue | Any | Yes | — | Option value. |
args... | Any | Variadic | — | Optional delimiter/offset/append and name-value options. |
Returns
| Name | Type | Description |
|---|---|---|
bytesWritten | NumericScalar | Number of bytes written to the output file. |
Errors
| Identifier | When | Message |
|---|---|---|
| — | Argument sequence or name-value grammar is malformed. | dlmwrite: invalid argument configuration |
| — | Filename is missing, empty, or not a scalar string/char vector. | dlmwrite: invalid filename input |
| — | Option name or value is invalid. | dlmwrite: invalid option value |
| — | Input data cannot be converted to a supported numeric/logical matrix. | dlmwrite: invalid input data |
| — | Input matrix is not 2-D. | dlmwrite: input must be 2-D |
| — | Numeric precision format is invalid or unsupported. | dlmwrite: invalid precision format |
| — | File inspection/open/write/flush operations fail. | dlmwrite: file write failed |
| — | Row or column offsets overflow or request an impractically large file layout. | dlmwrite: requested output layout is too large |
How dlmwrite works
- Accepts real numeric or logical arrays up to two dimensions (trailing singleton dimensions are ignored). All eight integer classes serialize directly from authoritative storage at default precision, including uint64 values beyond flintmax. Logical values are converted to
0/1. - The default delimiter is a comma. Supply a character vector, string scalar, or control sequence (
"\t","\n","\r") to change it. Delimiters must not be empty. - Positional syntax matches MATLAB:
dlmwrite(filename, M, delimiter)anddlmwrite(filename, M, delimiter, row, col)provide quick overrides. Row/column offsets are zero-based and insert blank rows/columns filled with the delimiter before the numeric data. - Name-value pairs extend any syntax:
'-append'appends to an existing file,'delimiter'overrides the separator,'precision'accepts either a scalar (significant digits) or a C-style printf format such as'%.6f','newline'chooses between'pc'(CRLF),'unix'(LF), or'mac'(CR), and'roffset'/'coffset'mirror the positional offsets. Typed integer offsets and precision counts are decoded exactly. Row and column additions are checked before file access, and layouts above 50,000,000 fields reject with a controlled size error. - Explicit precision intentionally enters the floating formatting domain; default integer formatting remains exact.
- MATLAB documents complex numeric and numeric cell input and documents no output argument. RunMat currently rejects complex/cell data; requesting RunMat's byte-count output is a named extension.
- Empty fields created by offsets are emitted as empty tokens separated by the delimiter, matching MATLAB's behaviour.
- Files are opened in text mode. When appending, RunMat preserves the existing newline convention and honours offsets relative to the end of the file.
- Paths beginning with
~expand to the user's home directory before writing, matching other RunMat I/O builtins.
Does RunMat run dlmwrite on the GPU?
dlmwrite performs all formatting on the CPU. With RunMat extensions enabled, resident input is gathered through the active acceleration provider before serialisation; strict compatibility mode rejects that form.
GPU memory and residency
No. dlmwrite gathers GPU-resident tensors only when RunMat extensions are enabled; public MATLAB documentation does not advertise gpuArray input support.
Examples
Writing a numeric matrix with the default comma delimiter
A = [1 2 3; 4 5 6];
dlmwrite("scores.csv", A)Using a semicolon delimiter and positional offsets
B = magic(3);
dlmwrite("offset.txt", B, ";", 1, 2)Appending data with explicit row and column offsets
dlmwrite("log.txt", 1:3);
dlmwrite("log.txt", 10:12, "-append", "roffset", 1, "coffset", 1)Controlling precision with significant digits
vals = [12.34567, pi];
dlmwrite("precision3.csv", vals, "precision", 3)Emitting fixed-point values with a printf-style format string
dlmwrite("fixed.txt", rand(2, 2), "precision", "%.6f", "delimiter", "\t")Writing resident data with Windows line endings
G = gpuArray(single([1.5; 2.5; 3.5]));
dlmwrite("gpu_pc.txt", G, "newline", "pc")Expected output:
% Data is gathered from the GPU and written using CR/LF line endings.Using dlmwrite with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how dlmwrite changes the result.
Run a small dlmwrite example, explain the result, then change one input and compare the output.
FAQ
Which data types does dlmwrite support?⌄
Real numeric and logical arrays up to two dimensions. Use writematrix/writecell for text or heterogeneous data.
How does the '-append' flag interact with offsets?⌄
Offsets are applied relative to the end of the existing file. '-append','roffset',2 inserts two blank delimiter-filled rows before writing the new data.
What happens if I request both positional and name-value offsets?⌄
RunMat follows MATLAB by allowing both; the last specification wins. For clarity, prefer one style per call.
Can I combine '-append' with positional delimiter arguments?⌄
Yes. For example dlmwrite(fname, M, ';', '-append') uses the semicolon delimiter and appends to the file.
Does 'precision', N control decimal places or significant digits?⌄
It controls significant digits (like MATLAB's %.*g). For fixed decimal places, pass a printf-style format such as '%.6f'.
Which line endings are supported?⌄
'newline','pc' emits \r\n (Windows). 'newline','unix' emits \n, and 'newline','mac' emits \r. The default matches the current platform.
How are NaN and Inf values written?⌄
They are emitted verbatim as NaN, Inf, or -Inf, independent of the precision setting, matching MATLAB.
How are offsets represented in the file?⌄
roffset produces blank delimiter-separated rows, while coffset inserts empty fields before each data row. Downstream tools will see empty strings for the offset cells.
Does dlmwrite normalise path separators?⌄
No. Paths are passed directly to the OS after optional ~ expansion, exactly like MATLAB.
Should new code use dlmwrite?⌄
Prefer writematrix for new code. Use dlmwrite only when maintaining legacy scripts that rely on its exact output.
Related Io functions
Tabular
arrayDatastore · csvread · csvwrite · detectImportOptions · dlmread · fileDatastore · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · spreadsheetImportOptions · writecell · writematrix · 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
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how dlmwrite is executed, line by line, in Rust.
- View the source for dlmwrite 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.