# MAT

This is an experimental feature that may change in future versions.
It is provided for compatibility with other dialects of BASIC and to enhance the code readibility of the Z80 version.

## Introduction

The MAT statement can be used to perform a number of matrix operations. Matrices are represented by arrays. Individual matrices can have any number of dimensions and be any size, but several operations rely on the matrices they are working on being a particular size, shape or type.

Matrix operations follow the general form:

`MAT <array-var>() = <operation>`

The array used to store the result of the matrix operation must have been dimensioned beforehand using the DIM statement. For example, to set a three-by-three array a to the identity matrix, one could use the IDN constant:

```DIM a(2,2)
MAT a() = IDN```

## Assignment

You can copy one numeric matrix to another by assigning one to the other:

`MAT b() = a()`

Both arrays must have the same number of dimensions and be the same size, but do not have to be the same type. If you assign an array of real numbers to an array of integers then each element will be truncated appropriately.

## Constant Operations

### ZER

The ZER constant sets all array elements to zero (in the case of numeric arrays) or the empty string (in the case of string arrays). The array can have any number of dimensions, be any shape and be any size.

`MAT a() = ZER`

### CON

The CON constant sets all numeric array elements to one. This operation may not be used with string arrays. The array can have any number of dimensions, be any shape and be any size.

`MAT a() = CON`

### CON(expr)

The CON(expr) constant sets all numeric array elements to the result of the expression expr. This operation may not be used with string arrays. The array can have any number of dimensions, be any shape and be any size.

`MAT a() = CON(SQR(PI))`

### IDN

The IDN constant sets the array to an identity matrix. The array must be numeric, be two-dimensional and be square, but can be any size.

```DIM a(3,3)
MAT a() = IDN```

The elements that lie on the diagonal between the top-left corner and bottom-right corner of the array are set to one; every other element is set to zero. The above sample code would produce the following matrix:

```1 0 0 0
0 1 0 0
0 0 1 0
0 0 0 1```

## Arithmetic

You can perform matrix arithmetic using the following syntax:

`MAT <result>() = <op1> <operator> <op2>`

The available operators are listed below. You may only perform a single operation in each MAT statement. Scalar values must be surrounded with parentheses.

### Addition

You can add two numeric matrices together with the + operator. Both matrices must have the same number of dimensions and be the same size.

`MAT c() = a()+b()`

Each element in a() is added to each element in b() and stored in c() in turn.

### Subtraction

You can subtract two numeric matrices together with the - operator. Both matrices must have the same number of dimensions and be the same size.

`MAT c() = a()-b()`

Each element in b() is subtracted from each element in a() and stored in c() in turn.

### Multiplication

You can multiply two numeric matrices together with the * operator. Both matrices must be two dimensional.

`MAT c() = a()*b()`

The result must have the same number of rows as the first operand and the same number of columns as the second operand. The second operand must have the same number of rows as the number of columns in the first operand.

```10 DIM a(1,2),b(2,3),product(1,3)
20 FOR i=0 TO 1:FOR j=0 TO 2:a(i,j)=j+i*3+1:NEXT j:NEXT i
30 FOR i=0 TO 2:FOR j=0 TO 3:b(i,j)=j+i*4+1:NEXT j:NEXT i
40 MAT product()=a()*b()
50 @%=&904
60 MAT PRINT a(),b(),product()```

The above sample program produces the following output:

```   1   2   3
4   5   6

1   2   3   4
5   6   7   8
9  10  11  12

38  44  50  56
83  98 113 128```

## Functions

### TRN

The TRN function transposes a numeric matrix - in effect, it swaps the rows and columns.

`MAT b() = TRN(b())`

Both matrices must have two dimensions, and the number of rows in one must equal the number of columns in the other and vice-versa. You may not transpose a matrix to itself.

``` 10 REM Dimension and populate a sample 2x3 matrix:
20 DIM a%(1,2)
30 a%(0,0)=1:a%(0,1)=2:a%(0,2)=3
40 a%(1,0)=4:a%(1,1)=5:a%(1,2)=6
50 REM Create a transposed version of the above matrix:
60 DIM b%(2,1)
70 MAT b%()=TRN(a%())
80 REM Print both matrices:
90 @%=&902
100 MAT PRINT a%(),b%()```

The above sample program produces the following output:

``` 1 2 3
4 5 6

1 4
2 5
3 6```

## Syntax

MAT <array-var>[()] = <operation>