Functions
SAT_OBJECT	sat3_creatematrix (SAT_OBJECT where, int rows, int cols, SAT_OBJECT fillobj, int allocsize)
	Create a matrix object with the given dimensions.
SAT_OBJECT	sat3_matrixgetrow (SAT_OBJECT matrix, int row)
	Get a pointer to a specific row of a matrix.
SAT_OBJECT	sat3_matrixget (SAT_OBJECT matrix, int row, int col)
	Get a pointer to a specific element of a matrix.
SAT_OBJECT	sat3_matrixfirst (SAT_OBJECT obj)
	Get a pointer to the first element of a matrix.
SAT_OBJECT	sat3_matrixnext (SAT_OBJECT obj)
	Get a pointer to the next element of a matrix.
BOOL	sat3_matrixsize (SAT_OBJECT matrix, int rowptr, int colptr)
	Get the size of a matrix object.
BOOL	sat3_matrixrowinsert (SAT_OBJECT matrix, int rowpos, SAT_OBJECT fillobj)
	Insert a row on a matrix.
BOOL	sat3_matrixrowremove (SAT_OBJECT matrix, int rowpos)
	Delete a row on a matrix.
BOOL	sat3_matrixcolinsert (SAT_OBJECT matrix, int colpos, SAT_OBJECT fillobj)
	Insert a column on a matrix.
BOOL	sat3_matrixcolremove (SAT_OBJECT matrix, int colpos)
	Delete a column on a matrix.
BOOL	sat3_matrixput (SAT_OBJECT matrix, int row, int col, SAT_OBJECT obj)
	Put an element on the matrix.

Detailed Description

This group includes all functions used to create/convert/manipulate matrices.

Function Documentation

SAT_OBJECT sat3_creatematrix	(	SAT_OBJECT	where,
		int	rows,
		int	cols,
		SAT_OBJECT	fillobj,
		int	allocsize
	)

Create a matrix object with the given dimensions.

Creates a new matrix of the given dimensions. To create 1-dimensional vectors set one of the dimensions to zero. If one of the dimensions is one, it creates a 2-dimensional array with one row or one column, instead of a vector. Initially, the matrix is filled with the given fill object.

Parameters:

where	Defines where to allocate memory from. Can be one of the following constants: ALLOC_HEAP Allocates from the C-heap using malloc() ALLOC_TEMPOB Allocates memory from the TEMPOB calculator area or... it can be an element (SAT_OBJECT) within a composite object, (array, list or any other).
rows	Number of rows, use zero to create a one-dimensional vector.
cols	Number of columns, use zero to create a one-dimensional vector.
fillobj	Object to fill all the elements of the new matrix
allocsize	Size in nibbles to allocate for the matrix.

Returns:: SAT_OBJECT with the new array object, or zero if it fails. When a SAT_OBJECT is given to the 'where' parameter, the same SAT_OBJECT is returned or 0 if error.

Note:: IMPORTANT - This function requires a garbage collection before program exit if ALLOC_TEMPOB was used. See fnncreate and sat3_garbcol for details.

See also:: Object creation and manipulation

BOOL sat3_matrixcolinsert	(	SAT_OBJECT	matrix,
		int	colpos,
		SAT_OBJECT	fillobj
	)

Insert a column on a matrix.

Add a column in a matrix at the specified position, filled with the specified filler object.

Parameters:

matrix	A matrix object.
colpos	Column at which the new column will be inserted. The new column will be inserted before the given one. Zero-based index.
fillobj	An arbitrary filler object that will be used to populate the new column.

Returns:: TRUE if successful, FALSE otherwise.

See also:: sat3_matrixcolremove

BOOL sat3_matrixcolremove	(	SAT_OBJECT	matrix,
		int	colpos
	)

Delete a column on a matrix.

Remove a column in a matrix at the specified position.

Parameters:

matrix	A matrix object.
colpos	Column that will be deleted. Zero-based index.

Returns:: TRUE if successful, FALSE otherwise.

See also:: sat3_matrixcolinsert

SAT_OBJECT sat3_matrixfirst ( SAT_OBJECT obj )

Get a pointer to the first element of a matrix.

Get a SAT_OBJECT pointing to the first element within a matrix object. If the matrix is one-dimensional it returns the first element, if it's two-dimensional it returns the first row (the matrix is treated as a one-dimensional array of one-dimensional vector elements).

Parameters:

obj	A matrix object, can be a row of a matrix.

Returns:: SAT_OBJECT with the first element, or zero if it fails. It can fail by giving an invalid object.

See also:: sat3_matrixgetrow sat3_matrixget sat3_matrixnext

SAT_OBJECT sat3_matrixget	(	SAT_OBJECT	matrix,
		int	row,
		int	col
	)

Get a pointer to a specific element of a matrix.

Get a SAT_OBJECT pointing to a specific element within a matrix object. One-dimensional vectors can be treated as either column-vectors or row-vectors. Simply set the row or column coordinate to zero.

Parameters:

matrix	A matrix object.
row	Row number, first row is zero.
col	Column number, first column is zero.

Returns:: SAT_OBJECT with the requested element, or zero if it fails. It can fail by giving an invalid matrix, a valid matrix with invalid dimensions, or invalid indices.

See also:: sat3_matrixgetrow sat3_matrixfirst sat3_matrixnext sat3_matrixput

SAT_OBJECT sat3_matrixgetrow	(	SAT_OBJECT	matrix,
		int	row
	)

Get a pointer to a specific row of a matrix.

Get a SAT_OBJECT pointing to a specific row within a matrix object. Each row is itself a one-dimensional matrix object, which can be manipulated with the same functions as its matrix container. If the matrix given is one-dimensional (a vector), it returns the nth element of the vector.

Parameters:

matrix	A matrix object.
row	Row number, first row is zero.

Returns:: SAT_OBJECT with the requested row, or zero if it fails. It can fail by giving an invalid matrix, a valid matrix with invalid dimensions, or an invalid index.

See also:: sat3_matrixget sat3_matrixfirst sat3_matrixnext

SAT_OBJECT sat3_matrixnext ( SAT_OBJECT obj )

Get a pointer to the next element of a matrix.

Get a SAT_OBJECT pointing to the next element within a matrix object. Two-dimensional matrices are treated as an array of rows, which are in turn one-dimensional matrices with elements. Therefore, sat3_matrixnext(any_element) will return the next element within the same row, null if the end of the row is reached. sat3_matrixnext(any_row) will return the next row, or null if the end of the matrix is reached.

Parameters:

obj	A matrix element, can be a row of a matrix or an element within a row.

Returns:: SAT_OBJECT with the first element, or zero if it fails. It can fail by giving an invalid object.

See also:: sat3_matrixgetrow sat3_matrixget sat3_matrixfirst

BOOL sat3_matrixput	(	SAT_OBJECT	matrix,
		int	row,
		int	col,
		SAT_OBJECT	obj
	)

Put an element on the matrix.

Replace the element at the specified coordinates with the given object. One-dimensional vectors can be treated as either column-vectors or row-vectors. Simply set the row or column coordinate to zero.

Parameters:

matrix	A matrix object.
row	Row number of the element. Zero-based index.
col	Column number of the element. Zero-based index.
obj	Arbitrary object to store inside the matrix.

Returns:: TRUE if successful, FALSE otherwise.

See also:: sat3_matrixget

BOOL sat3_matrixrowinsert	(	SAT_OBJECT	matrix,
		int	rowpos,
		SAT_OBJECT	fillobj
	)

Insert a row on a matrix.

Add a row in a matrix at the specified position, filled with the specified filler object.

Parameters:

matrix	A matrix object.
rowpos	Row at which the new row will be inserted. The new row will be inserted before the given row.
fillobj	An arbitrary filler object that will be used to populate the new row.

Returns:: TRUE if successful, FALSE otherwise.

See also:: sat3_matrixrowremove

BOOL sat3_matrixrowremove	(	SAT_OBJECT	matrix,
		int	rowpos
	)

Delete a row on a matrix.

Remove a row in a matrix at the specified position.

Parameters:

matrix	A matrix object.
rowpos	Row that will be deleted.

Returns:: TRUE if successful, FALSE otherwise.

See also:: sat3_matrixrowinsert

BOOL sat3_matrixsize	(	SAT_OBJECT	matrix,
		int *	rowptr,
		int *	colptr
	)

Get the size of a matrix object.

Obtain the number of rows and columns in a matrix object. A one-dimensional matrix will return 0 columns (one-dimensional matrices are treated as column vectors).

Parameters:

matrix	A matrix object.
rowptr	A pointer to an integer variable that will receive the number of rows.
colptr	A pointer to an integer variable that will receive the number of columns.

Returns:: TRUE on a valid matrix object with valid dimensions. When TRUE, *rowptr and *colptr contain a valid number of rows and columns respectively. It returns FALSE otherwise.

See also:: sat3_matrixgetrow sat3_matrixget sat3_matrixget sat3_matrixnext

Matrix functions

Functions

Detailed Description

Function Documentation