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

mtx/resize - Resize array dimensions

CONTENTS

Synopsis
Description
Error Handling
Examples
See Also
Author

mtx/resize ![matrix], dim
mtx/resize ![matrix], dim, value

Resizes a matrix array identified by the matrix argument to a new list of dimensions dim. Array dimensions are provided in the same format as for the mtx/def instruction. See mtx_def(5).

Matrix array resizing is non-destructive. The original array data will be left intact, only the dimensions used to address the data changes. However, if you reduce the size of an array, then the data that is no longer addressable is permanently lost.

Optionally, arrays of type psByte may have any new elements initialised by a block of data provided using the value argument. This data is used if the array is resized so that it is bigger than the original, in which case the new uninitialised memory will have value copied into it. THe value argument 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 uninitialised section. If it is too big, it will be silently truncated. If it is smaller than the uninitialised section, the outstanding bytes in the array 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, or if a referenced object does not exist in the nexus or does not point to a matrix array.

mtx/resize P0, @[#10, #15]
	Resizes the matrix array pointed to in register P0 so that it has 150 elements in two dimensions.
mtx/resize ![a], #150
	Resizes the matrix array pointed to by the relative object reference so that it has 150 elements in a single dimension.
mtx/resize P0, P5, P2
	Resizes the matrix array (of type psByte) pointed to in register P0 so that it has the dimensions identified by register P5, and any new elements are initialised by the data in register P2.

pal_commands(5), pal_registers(5), pal_indices(5), ps_attributes(5), mtx_def(5), mtx_size(5), mtx_bsize(5), mtx_dim(5), mtx_bresize(5),
PROSE Assembly Language at prose.sourceforge.net.

Copyright (c) 2002-2011 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.