MAT MOVE

General Form:

MAT MOVE move_array [, locator_array] [,n] TO receiver_array
Where:
move_array= { alpha array [ (x [,y]) ] }
numeric array
locator_array= { alpha array }
alpha array element
receiver_array= { alpha array element [(x[, y])] }
numeric array element
alpha array [(x[, y])]
numeric array
n = Counter variable. A numeric scalar specifying the number of elements to be moved. After the move is complete the variable will be updated with the number of elements actually moved.
(x [,y]) = Designates a field within an alpha element
x= start position, counted from 1
y= length of the filed in bytes. If omitted it is taken to be the number of bytes remaining in the element

The MAT MOVE statement is used to transfer data on an element by element basis from one array to another. For alpha arrays only a subfield of each element need be moved. Transfers done this way are much faster than using a FOR or WHILE loop in KCML.

If no locator array is specified the data is moved from the move_array to the receiver_array one element at a time. If a locator array is specified then the elements are transferred according to the array subscripts specified in the array, the array being an alpha array with two byte elements. When moving from a single dimensioned move_array the elements are interpreted as two byte binary array subscripts and when moving from a two dimensioned array they are presumed to be two single byte binary subscripts. Locator arrays can be generated by the MAT SORT statement or created programatically. The two byte element size limits the use of locator arrays to move_arrays of 65535 elements or less.

The transfer can be started at a particular element in the receiver_array by specifying an array element explicitly e.g.

MAT MOVE a()TO b(5)

will copy the a() elements to b() starting at b(5). You can also start with a particular element of a locator array by specifying the locator as an array element. You can only start with the first element of the move_array however.

If the move_array is an alpha array it is possible to specify a subfield of each element to transfer e.g.

DIM a$(10)16, b$(20)10
MAT MOVE a$()(2,4) TO b$()

is equivalent to

DIM a$(10)16, b$(20)10
FOR i=1 TO DIM(a$(),1)
b$(i) = STR(a$(i),2,4)
NEXT i

and

DIM a$(20)16, b$(10)10
MAT MOVE a$()(2,4) TO b$()(10)

is equivalent to

DIM a$(20)16, b$(10)10
FOR i=1 TO DIM(b$(),1)
STR(b$(i),10) = STR(a$(i),2,4)
NEXT i

Data is transferred element by element until one of the following end conditions is true:

  1. The end of the move_array is reached on a direct transfer
  2. The end of the locator_array is reached for an indirect transfer.
  3. A binary HEX(0000) is found in the locator_array
  4. The number of elements specified in the optional counter variable n has been copied.
  5. The receiver array has been filled

When the transfer is completed the optional counter, if present, will be updated with the actual number of transferred elements.

If is possible to MAT MOVE between alpha arrays and numeric arrays or vice versa and KCML will reformat the elements according to conventions established by BASIC-2. This usage is now deprecated and is no longer documented.