Index | PAL Intro | Commands | Registers | Indices | Stack | Macros | Classes | Attributes | Errors

ps_matrix - Introduction to PROSE matrix arrays

CONTENTS

Pre-requisite Reading
Description
Matrix Pointers
Error Handling
See Also
Author

Please see pal_intro(5) for a general description of PAL and mtx_def(5) for a description of how to define matrix arrays.

Matrix arrays, as described in mtx_def(5), provide a mechanism for addressing a contiguous block of memory as one or more elements of a particular variable type, through single or multi dimensional array indices.

Matrix arrays are defined using one of the following instructions:

mtx/def	the target array is created in a specified location.
mtx/local	the target array is created with local scope.
mtx/static	the target array is created with static scope.
mtx/global	the target array is created with global scope.

The following example creates an array called "forms" containing five string variables:

.setup   % Set-up forms array attr/load P0, [psString] mtx/local P1, P0, [forms], #5

The array is initially zeroed, so that each string contains a NULL pointer. There are two ways to initialise elements in a matrix array. The first is to use the mtx/set instruction, as described in mtx_set(5). The following example populates the first two elements:

.init_array   % Initialise first two elements (0 and 1) mtx/set P1, #0, [Sonata] mtx/set P1, #1, [Rondo]

The second method uses a matrix pointer. See MATRIX POINTERS.

Likewise there are two ways to read elements in a matrix array. The first is to use the mtx/get instruction, as described in mtx_get(5). The second method uses a matrix pointer. See MATRIX POINTERS.

MATRIX POINTERS

A matrix pointer is a pointer into a matrix array that can be moved around to address individual elements within it. Matrix pointers can be used to initialise and to read elements.

A matrix pointer is created using var/def with the psMatrixRef attribute. This instruction will also add the psMatrixRef class to the object, which brings with it two additional virtual attributes psMatrixIdx and psMatrixVal.

The psMatrixIdx attribute can be used to set the index position that will be addressed by the next read or write to the psMatrixVal attribute. The psMatrixVal attribute exposes the addressed element for read or write operations using any instruction that is valid on any normal attribute.

Simple pointer arithmetic may be performed on the psMatrixRef attribute, where increment/decrement/add/subtract operations move the pointer one element at a time around the array.

The following example populates the third and fourth elements in our "forms" array:

.setup_ptr   % Set-up matrix pointer attr/load P2, [psMatrixRef] var/local P3, P2, [pforms], P1 % When first initialised, the pointer addresses the first array % element (0), we need to set it to point to the third element, % which we can do by modifying the psMatrixIdx attribute attr/mod P3, [psMatrixIdx], #2 .init_array2   % Initialise third element (2) by using the psMatrixVal % attribute associated with the matrix pointer attr/load P4, [psMatrixVal] attr/mod P3, P4, [Prelude] % Advance pointer by adding 1 to psMatrixRef op/incr P3 % Now initialise the fourth element (3) attr/mod P3, P4, [Fugue]

Using the matrix pointer, it is now possible to read and change any element within the array. In the following example, we display all elements:

.display   % Matrix pointer is already in register P3 and we previously used % attr/load to put psMatrixVal into P4 attr/mod P3, [psMatrixIdx], #0 reg/load P5, ![.prose.sys.io], A, #0 attr/load P6, [psStreamOut] % Exit on out of bounds error error/jmp &[.exit], ![.prose.error.sys.OutOfBounds] .loop   % Loop through the array, displaying each element until % we receive an out of bounds error attr/copy P7, P3, P4 reg/copy P7, A, [: ], P7, [\n] attr/add P5, P6, P7 % Advance the pointer and our counter op/incr P3, A % Loop until error local/jmp &[.loop] .exit

A runtime error is generated if an attempt is made to address an element that is outside the bounds of the array, or to move a matrix pointer outside those bounds, or if an argument is of the wrong type esp. if the data you are attempting to set via a matrix pointer is not suitable for the array type.

pal_intro(5), pal_commands(5), mtx_def(5), mtx_set(5), mtx_get(5), mtx_dim(5), mtx_size(5), mtx_bsize(5), mtx_resize(5), mtx_bresize(5), var_def(5), ps_classes(5), ps_attributes(5),
PROSE Assembly Language at prose.sourceforge.net.

Copyright (c) 2002-2017 Mark R. Bannister <cambridge@users.sourceforge.net>.

This is free software and can be downloaded from prose.sourceforge.net; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.