3.1.4.4 Related utility functions

A small selection of additional functions that are likely to be of use to developers concerned with matrix operations has been incorporated into the API to save the trouble of reinventing them, although doing so would be straightforward. They are described in this section without further motivation.

Function: void *avm_matrix_transposition (void *matrix, int rows, int cols, size_t item_size)

This function takes the address of an arbitrary rectangular matrix represented as a contiguous array (not a list) and transposes it in place. That is, this function transforms an m by n matrix to an n by m matrix by exchanging the i,jth element with the j,ith element for all values of i and j.

The numbers of rows and columns in the matrix are given by the parameters rows and cols, respectively, and the size of the entries in bytes is given by item_size.

The matrix is assumed to be in row major order, but this function is applicable to matrices in column major order if the caller passes the number of columns in rows and the number of rows in cols.

Alternatively, this function can be seen as a conversion between the row major and the column major representation of a matrix. An m by n matrix in row major order will be transformed to the same m by n matrix in column order, or from column order to row order.

A notable feature of this function is that it allocates no memory so there is no possibility of a memory overflow even for very large matrices, unlike a naive implementation which would involve making a temporary copy of the matrix. There is a possibility of a segmentation fault if invalid pointers or dimensions are given.

Function: void *avm_matrix_reflection (int upper_triangular, void *matrix, int n, size_t item_size)

This function takes a symmetric square matrix of dimension n containing entries of item_size bytes each and fills in the redundant entries.

If upper_triangular is non-zero, the upper triangle of the matrix is copied to the lower triangle. If upper_triangular is zero, the lower triangular entries are copied to the upper triangle.

These conventions assume row major order. If the matrix is in column major order, then the caller can either transpose it in place before and after this function by avm_matrix_transposition, or can complement the value of upper_triangular.

Note that this function may be unnecessary for LAPACK library functions that ignore the redundant entries in a symmetric matrix, because they can be left uninitialized, but it is included for the sake of completeness.

Function: list *avm_row_number_array (counter m, int *fault)

A fast, memory efficient finite map from natural numbers to their list representations can be obtained by using this function as an alternative to avm_natural or avm_recoverable_natural when repeated evaluations of numbers within a known range are required (Simple Operations and Recoverable Operations).

Given a positive integer m, this function allocates and returns an array of m lists whose ith entry is the list representation of the number i as explained in Representation of Numeric and Textual Data.

An amount of memory proportional to m is used for the array and its contents. If there is insufficient memory, a NULL value is returned and the integer referenced by fault is set to a non-zero value.

Function: void avm_dispose_rows (counter m, list *row_number)

This function reclaims an array row_number of size m returned by avm_row_number_array, and its contents if any. A NULL pointer is allowed as the row_number parameter and will have no effect, but an uninitialized pointer will cause a segmentation fault.

Function: void avm_initialize_matcon ();

This function initializes some static variables used by the functions declared in ‘matcon.h’ and should be called before any of them is called or they might not perform according to specifications.

Function: void avm_count_matcon ();

This function frees the static variables allocated by avm_initialize_matcon and is used to verify the absence of memory leaks. It should be called after the last call to any functions in ‘matcon.h’ but before avm_count_lists if the latter is being used (Simple Operations).

This document was generated on December 10, 2012 using texi2html 1.82.