read matrices read

## Syntax

    [x] = read(file-desc,m,n,[format])
                [x]=read(file-desc,m,n,k,format)

## Arguments

file-desc

  character string specifying the file name or integer value specifying logical unit (fortran, see file).

m, n

  integers (dimensions of the matrix x). Set m=-1 if you do not know the numbers of rows, so the whole file is read.

format

  character string specifying a "Fortran" format. It must begin with a right parenthesis and end with a left parenthesis.Formats cannot mix floating point or character edition modes.

k

  integer or vector of integer

## Description

reads row after row the `mxn` matrix `x` (`n=1` for character chain) in the file `file-desc` (string or integer). Each row of the matrix `x` begin in a new line of `file-desc` file. Depending on `format`, a given row of the `x` matrix may be read from more than one line of `file-desc` file.

The type of the result will depend on the specified format. If format contains only `(d,e,f,g)` descriptors the function tries to read numerical data (the result is matrix of real numbers).

If format contains only `a` descriptors the function tries to read character strings (the result is a character string column vector). In this case n must be equal to 1.

The character strings are truncated when they are longuer than 4093.

Examples for `format`:

    (1x,e10.3,5x,3(f3.0))
    (10x,a20)

When format is omitted data are read using numerical free format: blank, comma and slash may be used as data separators, n*v may be use to represent n occurrences of value n.

A direct access file can be used if using the parameter `k` which is is the vector of record numbers to be read (one record per row), thus `m` must be `m=prod(size(k))`.

To read on the keyboard use `read(%io(1),...)`.

Last line of data files must be terminated by a newline to be taken into account.

## Examples

    mdelete(TMPDIR + '/foo');
    A = rand(3,5);
    write(TMPDIR + '/foo', A);
    B = read(TMPDIR + '/foo', 3, 5);
    B = read(TMPDIR + '/foo', -1, 5);
    read(%io(1), 1, 1, '(a)')  // waits for user's input

## See also

- write
- load
- file
- x_dialog
- mscanf
- mfscanf
- msscanf
- fscanfMat