Main Content

dlmread

(Not recommended) Read ASCII-delimited file of numeric data into matrix

collapse all in page

dlmread is not recommended. Use readmatrix instead. For more information, see Compatibility Considerations.

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.

example

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

example

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].

example

Examples

collapse all

Open Live Script

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.

Open Live Script

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.

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

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

collapse all

File name, specified as a character vector or string.

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

Data Types: char | 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

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

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

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

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.

Version History

Introduced before R2006a

collapse all

R2019a: dlmread is not recommended

dlmread is not recommended. Use readmatrix instead. There are no plans to remove dlmread.

Starting in R2019a, use the readmatrix function to read a matrix from a delimited text file. The readmatrix function has these advantages over the dlmread function:

  • Better cross-platform support and performance

  • Automatic detection of data format and types

  • Ability to use import options to control the data import process, including the handling of errors and missing data

This table shows typical usages of dlmread and how to update your code to use readmatrix instead.

Not Recommended

Recommended

M = dlmread(filename)
 
M = readmatrix(filename)

See Also

| | | |

Topics