Scilab Function
Last update : 8/11/2004

read - matrices read

### Calling Sequence

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

### Parameters

- `file-desc`: character string specifying the file name or integer value specifying logical unit (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, specifies a "Fortran" format. This`character string 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. Warning: 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 datas 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),...)`.

### Remark

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

### Examples

    if MSDOS then unix('del foo');
    else unix('rm -f foo'); end
    A=rand(3,5); write('foo',A);
    B=read('foo',3,5)
    B=read('foo',-1,5)
    read(%io(1),1,1,'(a)')  // waits for user's input

### See Also

`file`, `readb`, `write`, `x_dialog`, `mscanf`, `mfscanf`, `msscanf`, `fscanfMat`,