RunMat
GitHub

View all functions

CategoryIo: Tabular

csvwrite — Write numeric matrices to comma-separated text files using MATLAB-compatible offsets.

csvwrite(filename, M) writes a numeric matrix to a comma-separated text file. The builtin honours MATLAB's historical zero-based row/column offset arguments so that existing scripts continue to behave identically in RunMat.

How does the csvwrite function behave in MATLAB / RunMat?

  • Only real numeric or logical inputs are accepted. Logical values are converted to 0 and 1 before writing. Complex and textual inputs raise descriptive errors.
  • csvwrite(filename, M, row, col) starts writing at zero-based row row and column col, leaving earlier rows blank and earlier columns empty within each row. Offsets must be non-negative integers.
  • Matrices must be 2-D (trailing singleton dimensions are ignored). Column-major ordering is respected when serialising to text.
  • Numbers are emitted using MATLAB-compatible short g formatting (%.5g). NaN, Inf, and -Inf tokens are written verbatim.
  • Existing files are overwritten. csvwrite does not support appending; switch to writematrix with 'WriteMode','append' when the behaviour is required.
  • Paths that begin with ~ expand to the user's home directory before writing.

GPU behavior

csvwrite always executes on the host CPU. When the matrix resides on the GPU, RunMat gathers the data through the active acceleration provider before serialisation. No provider hooks are required, and the return value reports the number of bytes written after the gather completes.

GPU residency

No additional steps are necessary. csvwrite treats GPU arrays as residency sinks: data is gathered back to host memory prior to writing. This matches MATLAB's behaviour, where file I/O always operates on host-resident values.

Examples of using csvwrite in MATLAB / RunMat

Writing a numeric matrix to CSV

A = [1 2 3; 4 5 6];
csvwrite("scores.csv", A)

Starting output after a header row

fid = fopen("with_header.csv", "w");
fprintf(fid, "Name,Jan,Feb\nalpha,1,2\nbeta,3,4\n");
fclose(fid);

csvwrite("with_header.csv", [10 20; 30 40], 1, 0)

Skipping leading columns before data

B = magic(3);
csvwrite("offset_columns.csv", B, 0, 2)

Exporting logical masks as numeric zeros and ones

mask = [true false true; false true false];
csvwrite("mask.csv", mask)

Writing GPU-resident data without manual gather

G = gpuArray(single([0.1 0.2 0.3]));
bytes = csvwrite("gpu_values.csv", G)

Expected output:

bytes = 12

Persisting a scalar value for downstream tools

total = sum(rand(5));
csvwrite("scalar.csv", total)

FAQ

Why must the input be numeric or logical?

csvwrite predates MATLAB's table and string support and only serialises numeric values. Provide numeric matrices or logical masks, or switch to writematrix when you need to mix text and numbers.

Are row and column offsets zero-based?

Yes. row = 1 skips one full line before writing, and col = 2 inserts two empty comma-separated fields at the start of each written row.

Can I append to an existing CSV with csvwrite?

No. csvwrite always overwrites the destination file. Use writematrix with 'WriteMode','append' or manipulate the file with lower-level I/O functions.

How are NaN and Inf values written?

They are emitted verbatim as NaN, Inf, or -Inf, matching MATLAB's text representation so that downstream tools can parse them consistently.

What line ending does csvwrite use?

The builtin uses the platform default (\r\n on Windows, \n elsewhere). Most CSV consumers handle either convention transparently.

See also

csvread, readmatrix, writematrix, fprintf, gpuArray, gather

Source & Feedback