dlmread

Read ASCII-delimited file of numeric data into matrix

Syntax

M = dlmread(filename)

M = dlmread(filename,delimiter)

M = dlmread(filename,delimiter,R1,C1)

M = dlmread(filename,delimiter,[R1 C1 R2 C2])

Description

M = dlmread(filename) reads an ASCII-delimited numeric data file into matrix M. The dlmread function detects the delimiter from the file and treats repeated white spaces as a single delimiter.

M = dlmread(filename,delimiter) reads data from the file using the specified delimiter and treats repeated delimiter characters as separate delimiters.

M = dlmread(filename,delimiter,R1,C1) starts reading at row offset R1 and column offset C1. For example, the offsets R1=0, C1=0 specify the first value in the file.

To specify row and column offsets without specifying a delimiter, use an empty character as a placeholder, for example, M = dlmread(filename,'',2,1).

M = dlmread(filename,delimiter,[R1 C1 R2 C2]) reads only the range bounded by row offsets R1 and R2 and column offsets C1 and C2. Another way to define the range is to use spreadsheet notation, such as 'A1..B7' instead of [0 0 6 1].

Examples

Read Entire Delimited File

Read the sample file, count.dat.

M = dlmread('count.dat')

M = 24×3

    11    11     9
     7    13    11
    14    17    20
    11    13     9
    43    51    69
    38    46    76
    61   132   186
    75   135   180
    38    88   115
    28    36    55
      ⋮

dlmread detects the delimiter from the file and returns a matrix.

Read File Containing Empty Delimited Fields

Write two matrices to a file, and then read the entire file using dlmread.

Export a matrix to a file named myfile.txt. Then, append an additional matrix to the file that is offset one row below the first.

X = magic(3);
dlmwrite('myfile.txt',[X*5 X/5],' ')
dlmwrite('myfile.txt',X,'-append', ...
   'roffset',1,'delimiter',' ')

View the file contents.

type myfile.txt

40 5 30 1.6 0.2 1.2
15 25 35 0.6 1 1.4
20 45 10 0.8 1.8 0.4
  
8 1 6
3 5 7
4 9 2

Read the entire file using dlmread.

M = dlmread('myfile.txt')

M = 6×6

   40.0000    5.0000   30.0000    1.6000    0.2000    1.2000
   15.0000   25.0000   35.0000    0.6000    1.0000    1.4000
   20.0000   45.0000   10.0000    0.8000    1.8000    0.4000
    8.0000    1.0000    6.0000         0         0         0
    3.0000    5.0000    7.0000         0         0         0
    4.0000    9.0000    2.0000         0         0         0

When dlmread imports a file containing nonrectangular data, it fills empty fields with zeros.

Read Delimited File Starting At Specific Row and Column Offset

Create a file named dlmlist.txt that contains column headers and space-delimited values.

test max min direction
10 27.7 12.4 12
11 26.9 13.5 18
12 27.4 16.9 31
13 25.1 12.7 29  

Read the numeric values in the file. Specify a space delimiter, a row offset of 1, and a column offset of 0.

filename = 'dlmlist.txt';
M = dlmread(filename,' ',1,0)

M =

   10.0000   27.7000   12.4000   12.0000
   11.0000   26.9000   13.5000   18.0000
   12.0000   27.4000   16.9000   31.0000
   13.0000   25.1000   12.7000   29.0000

Read Specific Range from Delimited File

Create a file named dlmlist.txt that contains column headers and space-delimited values.

test max min direction
10 27.7 12.4 12
11 26.9 13.5 18
12 27.4 16.9 31
13 25.1 12.7 29  

Read only the last two rows of numeric data from the file.

M = dlmread('dlmlist.txt',' ',[3 0 4 3])

M =

   12.0000   27.4000   16.9000   31.0000
   13.0000   25.1000   12.7000   29.0000

Input Arguments

filename — File name

character vector | string

File name, specified as a character vector or string.

Example: 'myFile.dat' or "myFile.dat"

Data Types: char | string

delimiter — Field delimiter character

character vector | string

Field delimiter character, specified as a character vector or string. Use '\t' to specify a tab delimiter.

Example: ',' or ","

Example: ' ' or " "

Data Types: char | string

R1 — Starting row offset

0 (default) | nonnegative integer

Starting row offset, specified as a nonnegative integer. The first row has an offset of 0.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

C1 — Starting column offset

0 (default) | nonnegative integer

Starting column offset, specified as a nonnegative integer. The first column has an offset of 0.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

R2 — Ending row offset

nonnegative integer

Ending row offset, specified as a nonnegative integer. The first row has an offset of 0.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

C2 — Ending column offset

nonnegative integer

Ending column offset, specified as a nonnegative integer. The first column has an offset of 0.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Tips

• Skip header rows or columns by specifying row and column offsets. All values in the file other than headers must be numeric.

Algorithms

dlmread fills empty delimited fields with zero. When the dlmread function reads data files with lines that end with a nonspace delimiter, such as a semicolon, it returns a matrix, M, that has an additional last column of zeros.

dlmread imports any complex number as a whole into a complex numeric field. This table shows valid forms for a complex number.

Form	Example
±<real>±<imag>i|j	5.7-3.1i
±<imag>i|j	-7j

Embedded white space in a complex number is invalid and dlmread regards it as a field delimiter.