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

mtx/def - Define a new matrix array

CONTENTS

Synopsis
Description
Defining Array Dimensions
Array Initialisation
Error Handling
Examples
See Also
Author

mtx/def write, attribute, ![target], [name], dim, bdim, value
mtx/def write, attribute, ![target], [name], dim, bdim
mtx/def write, attribute, ![target], [name], dim, value
mtx/def write, attribute, ![target], [name], dim
mtx/def write, attribute, ![target], [name]

mtx/local write, attribute, [name], dim, bdim, value
mtx/local write, attribute, [name], dim, bdim
mtx/local write, attribute, [name], dim, value
mtx/local write, attribute, [name], dim
mtx/local write, attribute, [name]

mtx/static write, attribute, [name], dim, bdim, value
mtx/static write, attribute, [name], dim, bdim
mtx/static write, attribute, [name], dim, value
mtx/static write, attribute, [name], dim
mtx/static write, attribute, [name]

mtx/global write, attribute, [name], dim, bdim, value
mtx/global write, attribute, [name], dim, bdim
mtx/global write, attribute, [name], dim, value
mtx/global write, attribute, [name], dim
mtx/global write, attribute, [name]

Defines and zeroes a new matrix array, with the type specified in the attribute argument. A matrix array is a contiguous block of memory that is divided up into elements of a size suitable for a given data type. The elements are addressed by single or multi-dimensional indices. The type must be a variable type as defined in ps_attributes(5).

The array will be called name, and sized according to the optional list of dimensions dim. The base of each dimension will be 0 unless a list of base dimensions bdim are also supplied. The array can be optionally initialised using a supplied value, which must be a text argument or a byte string (PSUNIT_TYPE_STRING). A reference to the resulting object will be stored in the write register as PSUNIT_TYPE_MATRIX.

The mtx/def instruction takes a target argument, which is the object underneath which to create the new array.

The mtx/local, mtx/static and mtx/global instructions have the same scope as var/local, var/static and var/global. See the var_def(5) man page for details.

In all cases, if the object already exists the necessary classes and attributes will be added to the object to make it suitable for use as an array. If the target object was already a matrix array, the old array will be replaced by a new array.

The attribute is either a text argument containing the name of the object attribute to add, or a PSUNIT_TYPE_ATTRDEF register returned by the attr/load instruction. The attribute must be a variable type as defined in ps_attributes(5).

The name may be a dot-separated path if the array is to be created underneath a subcontainer. If the path doesn’t already exist, it will be created. If a dot needs to be used in a name then prefix it with a backslash character (\).

The dim argument provides one or a list of dimensions to use in array initialisation. It may be a raw index or a list sequence. If it is a list sequence, you may use raw indices or GMP integers to define dimensions. GMP integers used as array dimensions are useful if you are working with large arrays on a platform that has more than 2^32 bytes of addressable memory.

The bdim argument provides one or a list of base dimensions to use in array initialisation. It must match the number of dimensions provided to dim. As with the dim argument, inside a list sequence you may optionally use GMP integers, this being the only means to supply negative indices. For example, #-5 would not produce the expected result when supplied with bdim, and will in fact cause a compile-time error. You would use @[-5] instead.

If the bdim argument is omitted, the default base of 0 will be used.

Arrays of type psByte may be initialised by the mtx/def instruction using the value argument. The value is an argument containing the data to add to the attribute. It may only be text (PSUNIT_TYPE_PALTEXT), a byte string (PSUNIT_TYPE_STRING), or encoded data (PSUNIT_TYPE_XVALUE). This data may fill all or part of the array. If it is too big, it will be silently truncated. If it is smaller than the array, the outstanding bytes will be zeroed.

If value is a register containing the type PSUNIT_TYPE_STRING or PSUNIT_TYPE_XVALUE and the instruction does not generate an error, then the register will be cleared as the data is now referenced elsewhere.

If value is encoded data (PSUNIT_TYPE_XVALUE) and the data encoding is not a byte string (psString), then it will be re-encoded as a byte string before processing.

A runtime error is generated if an argument is of the wrong type, if a named attribute does not exist in the schema, or if a referenced object does not exist in the nexus.

mtx/local P0, [psInteger], [idx], #100
	Creates a local array of 100 GMP integers called idx and stores a pointer to the new object in register P0. The array elements will be addressed using index numbers 0 to 99.
mtx/global NULL, [psString], [glob], @[#10, #5]
	Creates a global array of 50 strings called glob and discards the pointer to the new object. The array elements will be addressed using multiple dimensions, all base 0.
mtx/local PUSH, [psIndex], [a], #11, @[-5]
	Creates a local array of 11 raw index numbers called a and pushes a pointer to the new object onto the program stack. The array elements will be addressed using index numbers -5 to 5.
mtx/static P3, [psByte], [buf], #100, [Reeves]
	Creates a static array of 100 characters called buf, initialises it with the given string and stores a pointer to the new object in register P3.
mtx/local P11, [psFloat], [flt], @[#20, #10, #2], @[#1, #1, #1]
	Creates a local array of 400 GMP floating-point numbers called flt, arranged in a 3-dimensional grid, with the base of each dimension being 1 instead of the default base of 0.

pal_commands(5), pal_registers(5), pal_indices(5), ps_attributes(5), ps_matrix(5), mtx_set(5), mtx_dim(5), mtx_size(5), mtx_bsize(5), mtx_resize(5), mtx_bresize(5), var_def(5), var_addr(5), attr_add(5), itree_def(5), xtree_def(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.