RunMat
GitHub

View all functions

CategoryIo: Tabular

What does the dlmread function do in MATLAB / RunMat?

dlmread(filename) reads numeric data from an ASCII text file that uses a consistent delimiter between fields. Unlike csvread, dlmread lets you supply any single-character delimiter (including tabs or semicolons) or an ASCII code.

How does the dlmread function behave in MATLAB / RunMat?

  • Accepts character vectors or string scalars for filename. String arrays must contain exactly one element.
  • The delimiter is optional; when omitted, a comma (,) is used. Supply a character (for example ';'), a string scalar ("\t"), or a numeric ASCII code (9 for tab). Empty delimiter inputs are not allowed.
  • dlmread(filename, R, C) and dlmread(filename, delimiter, R, C) start reading at zero-based offsets R and C, skipping any earlier rows or columns.
  • dlmread(filename, range) and dlmread(filename, delimiter, range) accept a numeric vector [r1 c1 r2 c2] or [r1 c1] describing a rectangular slice. The indices are zero-based and inclusive. Excel-style addresses such as "B2:D6" are also accepted for compatibility with csvread.
  • Empty fields (for example two adjacent delimiters) are interpreted as 0. Tokens such as NaN, Inf, and -Inf are accepted (case-insensitive).
  • Any other nonnumeric token raises an error that identifies the offending row and column using one-based indices (matching MATLAB diagnostic messages).
  • Results are dense double-precision tensors laid out in column-major order. Empty files yield a 0×0 tensor.
  • Leading UTF-8 byte order marks (BOM) are stripped automatically to match MATLAB's handling of spreadsheets that emit BOM-prefixed text files.
  • Paths may include ~ to reference the home directory; RunMat expands the token before opening the file.

dlmread Function GPU Execution Behavior

dlmread performs file I/O and parsing on the CPU. Arguments are gathered from the GPU when needed, and the output tensor lives in host memory. Wrap the result in gpuArray if you need residency on a device. No provider hooks are involved.

Examples of using the dlmread function in MATLAB / RunMat

Reading comma-delimited data by default

writematrix([1 2 3; 4 5 6], "samples.csv");
M = dlmread("samples.csv");
delete("samples.csv");

Expected output:

M =
     1     2     3
     4     5     6

Importing semicolon-separated values

fid = fopen("scores.txt", "w");
fprintf(fid, "1;2;3\n4;5;6\n");
fclose(fid);

M = dlmread("scores.txt", ";");
delete("scores.txt");

Expected output:

M =
     1     2     3
     4     5     6

Using tab characters as the delimiter

fid = fopen("tabs.txt", "w");
fprintf(fid, "10\t11\t12\n13\t14\t15\n");
fclose(fid);

M = dlmread("tabs.txt", "\t");
delete("tabs.txt");

Expected output:

M =
    10    11    12
    13    14    15

Skipping a header row and column (zero-based offsets)

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

M = dlmread("with_header.txt", ",", 1, 1);
delete("with_header.txt");

Expected output:

M =
     1     2
     3     4

Extracting a rectangular range

fid = fopen("block.txt", "w");
fprintf(fid, "10,11,12,13\n14,15,16,17\n18,19,20,21\n");
fclose(fid);

sub = dlmread("block.txt", ",", [1 1 2 3]);
delete("block.txt");

Expected output:

sub =
    15    16    17
    19    20    21

Treating empty fields as zeros

fid = fopen("blanks.txt", "w");
fprintf(fid, "1,,3\n,5,\n7,8,\n");
fclose(fid);

M = dlmread("blanks.txt");
delete("blanks.txt");

Expected output:

M =
     1     0     3
     0     5     0
     7     8     0

Using a numeric ASCII code for the delimiter

fid = fopen("pipe.txt", "w");
fprintf(fid, "5|6|7\n8|9|10\n");
fclose(fid);

M = dlmread("pipe.txt", double('|'));
delete("pipe.txt");

Expected output:

M =
     5     6     7
     8     9    10

GPU residency in RunMat (Do I need gpuArray?)

dlmread always creates a CPU-resident tensor because the function performs file I/O synchronously on the host. If you need the data on the GPU, call gpuArray(dlmread(...)) or switch to readmatrix with the 'Like' option to direct the result to a device.

FAQ

Can I omit the delimiter argument?

Yes. When you omit the delimiter, dlmread assumes a comma. If you need another delimiter, pass it explicitly as a character, string scalar, or numeric ASCII code.

Are row and column offsets zero-based like MATLAB?

Yes. The R and C arguments count from zero. dlmread(filename, delimiter, 1, 2) skips the first row and the first two columns before reading data.

How do I specify a range?

Provide a numeric vector [r1 c1 r2 c2] (zero-based, inclusive) or an Excel-style address such as "B2:D5". You can pass the range with or without a delimiter argument.

What happens if the file contains text tokens?

Non-numeric fields trigger an error that includes the one-based row and column number of the offending token. Use readmatrix or readtable when you need to mix text and numbers.

How does dlmread treat empty cells?

Empty cells evaluate to 0, matching MATLAB behavior. This includes consecutive delimiters and trailing delimiters.

Can I use whitespace as the delimiter?

Yes. Pass " " (space), "\t" (tab), or the corresponding ASCII code. Multiple consecutive delimiters produce zeros where the values are missing.

Does dlmread respect locale-specific decimal separators?

No. Parsing always uses . as the decimal separator, consistent with MATLAB.

Does dlmread change the working directory?

No. Relative paths are resolved against the current working directory. dlmread never mutates global process state.

Why does the output stay on the CPU?

dlmread performs synchronous file I/O, so the result resides in host memory. Wrap the result with gpuArray if you want a device-resident tensor.

See Also

csvread, readmatrix, gpuArray, gather

Source & Feedback