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 |
How dlmwrite works
- Accepts real numeric or logical arrays up to two dimensions (trailing singleton dimensions are ignored). Complex inputs raise an error. 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. - 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. When the input array lives on a GPU, RunMat gathers it through the active acceleration provider before serialisation. No provider hooks are required, and the builtin returns once the host-side write completes. If no provider is registered, the same gather error surface as other residency sinks appears.
GPU memory and residency
No. dlmwrite gathers GPU-resident tensors automatically before writing. This mirrors MATLAB's behaviour, where dlmwrite always operates on host-resident values.
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")Selecting the Windows line ending while writing GPU data
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
csvread · csvwrite · dlmread · readmatrix · writematrix
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fullfile · genpath · getenv · ls · mkdir · movefile · path · pwd · rmdir · rmpath · run · savepath · setenv · tempdir · tempname
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite
Json
Http
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.