Functionality related to matrix constructs.
zmlMatrixA matrix construct of any given size. The values in a zmlMatrix are of floating-point type.
rows the amount of rows in the matrixcols the amount of columns in the matrixelements a 2D array of elements in the matrixThe functions for matrix-matrix and matrix-scalar operations are:
| Function name | Representation in operators |
|---|---|
zmlAddMats_r(v1, v2) | v1 + v2 |
zmlAddMats(v1, v2) | v1 += v2 |
zmlSubtractMats_r(v1, v2) | v1 - v2 |
zmlSubtractMats(v1, v2) | v1 -= v2 |
zmlMultiplyMats_r(v1, v2) | v1 * v2 |
zmlMultiplyMats(v1, v2) | v1 *= v2 |
| Function name | Representation in operators |
|---|---|
zmlAddMatScalar_r(v1, v2) | v1 + v2 |
zmlAddMatScalar(v1, v2) | v1 += v2 |
zmlSubtractMatScalar_r(v1, v2) | v1 - v2 |
zmlSubtractMatScalar(v1, v2) | v1 -= v2 |
zmlMultiplyMatScalar_r(v1, v2) | v1 * v2 |
zmlMultiplyMatScalar(v1, v2) | v1 *= v2 |
zmlDivideMatScalar_r(v1, v2) | v1 / v2 |
zmlDivideMatScalar(v1, v2) | v1 /= v2 |
| Function name | Representation in operators |
|---|---|
zmlMatEquals(v1, v2) | v1 == v2 |
zmlMatGT(v1, v2) | v1 > v2 |
zmlMatGTE(v1, v2) | v1 >= v2 |
zmlMatLT(v1, v2) | v1 < v2 |
zmlMatLTE(v1, v2) | v1 <= v2 |
For more information regarding the naming convention used for operator functions, see Home/Naming scheme of operator functions.
The_r operator functions allocate memory for their return values which must be freed to avoid memory leaks.
zmlMatrix zmlAllocMatrix(unsigned int rows, unsigned int cols)rows the amount of rows in the matrixcols the amount of columns in the matrixAllocate memory for a matrix struct, and return the empty matrix. Elements are NOT initialised!
After a matrix is created, it must be freed after use with a call to zmlFreeMatrix().void zmlFreeMatrix(zmlMatrix *mat)mat the matrix to free.Free a matrix's memory.
zmlMatrix zmlIdentityMatrix(unsigned int rows, unsigned int cols)rows the amount of rows in the matrixcols the amount of columns in the matrixAllocate and initialise an identity matrix with the given size. (All elements on the main diagonal are 1, others are 0).
After a matrix is created, it must be freed after use with a call to zmlFreeMatrix().zmlMatrix zmlZeroMatrix(unsigned int rows, unsigned int cols)rows the amount of rows in the matrixcols the amount of columns in the matrixAllocate and initialise a zero matrix with the given size.
After a matrix is created, it must be freed after use with a call to zmlFreeMatrix().zmlMatrix zmlCopyMatrix(zmlMatrix *val)val the matrix to be copied.Copy a matrix's values into a new matrix and return the duplicate. The original matrix is not freed.
The resultant matrix must be freed after use with zmlFreeMatrix().zmlVector zmlGetMatrixRow(zmlMatrix val, unsigned int index)val the matrix to be observedindex the index of the row to retrieve.
Get a specified row from the given matrix in the form of a vector. The size of this vector
is the same as the width (columns) of matrix val.
void zmlSetMatrixRow(zmlMatrix *mat, unsigned int index, zmlVector vec)mat the matrix to be modified.index the index of the row to set.vec the vector to set the row to.
Set a row in the given matrix to a specified vector. If the size of vec is less than the amount of columns in
mat, the remaining matrix elements will be left unchanged.
zmlVector zmlGetMatrixCol(zmlMatrix val, unsigned int index)val the matrix to be observedindex the index of the column to retrieve.
Get a specified column from the given matrix in the form of a vector.
The size of this vector is the same as the height (rows) of matrix val.
void zmlSetMatrixCol(zmlMatrix *mat, unsigned int index, zmlVector vec)mat the matrix to be modified.index the index of the column to set.vec the vector to set the column to.
Set a column in the given matrix to a specified vector. If the size of vec is less than the amount of rows in
mat, the remaining matrix elements will be left unchanged.
zmlMatrix zmlTransposed(zmlMatrix mat)mat the matrix to transpose.Returns the given matrix in its transposed state - that is to say, the rows and columns of the matrix are swapped.
This function produces a new matrix structure which must be freed with zmlFreeMatrix(). In cases where you would type, for example,mat = zmlTransposed(&mat), you should type zmlTranspose(&mat),
using the zmlTranspose() function instead.
void zmlTranspose(zmlMatrix *mat)mat the matrix to transpose.Transposes the given matrix by modifying it. This works as an alternative to zmlTransposed() that does not allocate any new memory; you should use this function instead in some cases to avoid memory leaks - see the warning in zmlTransposed().
void zmlAugmentVec(zmlMatrix *mat, zmlVector vec)mat the matrix to modify.vec the vector to augment onto mat.
Augments vector vec onto matrix mat. The size of the given matrix mat
increases when calling this function. The size of the vector must be equal to the amount of columns in the matrix!
void zmlAugmentMat(zmlMatrix *mat, zmlMatrix val)mat the matrix to modify.val the matrix to augment onto mat.
Augments matrix val onto matrix mat. The size of the given matrix mat
increases when calling this function. The amount of columns in val must be equal
to the amount of columns in mat!
mat.
void zmlCopyMatrixElements(zmlMatrix mat, floating arr[mat.rows][mat.cols])mat the specified matrix.arr the destination array.
Copies the elements from matrix mat into the specified 2D array arr.
This is useful for copying the elements of the matrix into the stack.
ZML_NULL_MATRIX
An undefined matrix with a size of 0. This is sometimes returned when functions fail (although functions will also print an error to
stdout when they return ZML_NULL_MATRIX).
elements array in undefined matrices is a null pointer - using ZML_NULL_MATRIX is very unsafe!