16.4.8.1 The READ Command

READ variable[(index[,index])]
     [/FILE=file]
     /FIELD=first TO last [BY width]
     [/FORMAT=format]
     [/SIZE=expression]
     [/MODE={RECTANGULAR | SYMMETRIC}]
     [/REREAD].

The READ command reads from a text file into a matrix variable. Specify the target variable just after the command name, either just a variable name to create or replace an entire variable, or a variable name followed by an indexing expression to replace a submatrix of an existing variable.

The FILE subcommand is required in the first READ command that appears within MATRIX. It specifies the text file to be read, either as a file name in quotes or a file handle previously declared on FILE HANDLE (see FILE HANDLE). Later READ commands (in syntax order) use the previous referenced file if FILE is omitted.

The FIELD and FORMAT subcommands specify how input lines are interpreted. FIELD is required, but FORMAT is optional. See The READ and WRITE Commands, for details.

The SIZE subcommand is required for reading into an entire variable. Its restricted expression argument should evaluate to a 2-element vector {n, m} or {n; m}, which indicates a n×m matrix destination. A scalar n is also allowed and indicates a n×1 column vector destination. When the destination is a submatrix, SIZE is optional, and if it is present then it must match the size of the submatrix.

By default, or with MODE=RECTANGULAR, the command reads an entry for every row and column. With MODE=SYMMETRIC, the command reads only the entries on and below the matrix’s main diagonal, and copies the entries above the main diagonal from the corresponding symmetric entries below it. Only square matrices may use MODE=SYMMETRIC.

Ordinarily, each READ command starts from a new line in the text file. Specify the REREAD subcommand to instead start from the last line read by the previous READ command. This has no effect for the first READ command to read from a particular file. It is also ineffective just after a command that uses the EOF matrix function (see EOF Matrix Function) on a particular file, because EOF has to try to read the next line from the file to determine whether the file contains more input.

Example 1: Basic Use

The following matrix program reads the same matrix {1, 2, 4; 2, 3, 5; 4, 5, 6} into matrix variables v, w, and x:

READ v /FILE='input.txt' /FIELD=1 TO 100 /SIZE={3, 3}.
READ w /FIELD=1 TO 100 /SIZE={3; 3} /MODE=SYMMETRIC.
READ x /FIELD=1 TO 100 BY 1/SIZE={3, 3} /MODE=SYMMETRIC.

given that input.txt contains the following:

1, 2, 4
2, 3, 5
4, 5, 6
1
2 3
4 5 6
1
23
456

The READ command will read as many lines of input as needed for a particular row, so it’s also acceptable to break any of the lines above into multiple lines. For example, the first line 1, 2, 4 could be written with a line break following either or both commas.

Example 2: Reading into a Submatrix

The following reads a 5×5 matrix from input2.txt, reversing the order of the rows:

COMPUTE m = MAKE(5, 5, 0).
LOOP r = 5 TO 1 BY -1.
  READ m(r, :) /FILE='input2.txt' /FIELD=1 TO 100.
END LOOP.

Example 3: Using REREAD

Suppose each of the 5 lines in a file input3.txt starts with an integer count followed by count numbers, e.g.:

1 5
3 1 2 3
5 6 -1 2 5 1
2 8 9
3 1 3 2

Then, the following reads this file into a matrix m:

COMPUTE m = MAKE(5, 5, 0).
LOOP i = 1 TO 5.
  READ count /FILE='input3.txt' /FIELD=1 TO 1 /SIZE=1.
  READ m(i, 1:count) /FIELD=3 TO 100 /REREAD.
END LOOP.