RunMat
GitHub

View all functions

CategoryIo: Tabular

What does the csvwrite function do in MATLAB / RunMat?

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.

csvwrite Function GPU Execution Behaviour

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.

Examples of using the csvwrite function in MATLAB / RunMat

Writing a numeric matrix to CSV

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

Expected contents of scores.csv:

1,2,3
4,5,6

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);

Expected contents of with_header.csv:

Name,Jan,Feb

10,20
30,40

Skipping leading columns before data

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

Expected contents of offset_columns.csv:

,,8,1,6
,,3,5,7
,,4,9,2

Exporting logical masks as numeric zeros and ones

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

Expected contents of mask.csv:

1,0,1
0,1,0

Writing GPU-resident data without manual gather

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

Expected behaviour:

% Data is gathered automatically from the GPU and written to disk.

Persisting a scalar value for downstream tools

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

Expected contents of scalar.csv:

2.5731

GPU residency in RunMat (Do I need gpuArray?)

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.

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