va_matrix

#include <va_matrix.h>

Defines

VA_MATRIX_DECL(TYPENAME)

A matrix template.

This macro is a template that is used to create a matrix implementation for each supported primitive type. All matrix types are bitwise identical and can be safely casted to each other. A generic typeless matrix is called va_matrix. Type-specific matrix implementations are named according to va_matrix_type as follows:

• int: va_imatrix

• float: va_fmatrix

• double: va_dmatrix

• va_fcomplex: va_fcmatrix

• va_dcomplex: va_dcmatrix

• va_real: va_rmatrix

• va_rcomplex: va_rcmatrix

In addition to the generic functions such as va_matrix_alloc, there are specialized versions for each matrix type (e.g. va_imatrix_alloc).

The header and data of a matrix are always stored contiguously in memory. In other words, the first element of a matrix immediately follows the header. Use the va_matrix_data function to get a pointer to it. The specialized versions such as va_dmatrix_data return a typed pointer.

Enums

enum va_matrix_type

Matrix types.

Values:

enumerator va_imatrix_type

enumerator va_fmatrix_type

enumerator va_dmatrix_type

enumerator va_fcmatrix_type

enumerator va_dcmatrix_type

enumerator va_bmatrix_type

enumerator va_rmatrix_type

enumerator va_cmatrix_type

Functions

va_matrix *va_matrix_alloc(va_matrix_type type, int rows, int columns)

Allocates an uninitialized matrix.

If rows or columns is negative or if the requested amount of memory cannot be allocated, returns NULL.

// Allocate a 4-by-4 integer matrix with uninitialized contents.
va_matrix* mat = va_matrix_alloc(va_imatrix_type, 4, 4);
// Same, but typed.
va_imatrix* imat = (va_imatrix*)va_matrix_alloc(va_imatrix_type, 4, 4);
// Still same, but easier.
va_imatrix* imat2 = va_imatrix_alloc(4, 4);
// Floating-point elements.
va_fmatrix* fmat = va_fmatrix_alloc(4, 4);

va_matrix *va_matrix_calloc(va_matrix_type type, int rows, int columns)

Allocates a matrix whose every element is initially zero.

If rows or columns is negative or if the requested amount of memory cannot be allocated, returns NULL.

// Allocate a 4-by-4 integer matrix with all elements initialized to zero.
va_matrix* mat = va_matrix_calloc(va_imatrix_type, 4, 4);
// Double precision
va_dmatrix* dmat = va_dmatrix_calloc(4, 4);

va_matrix *va_matrix_realloc(va_matrix *matrix, int rows)

Changes the size of the memory block allocated for data in matrix to hold the specified number of rows.

The semantics of this function are the same as the standard realloc() function: the implementation either increases or decreases the size of the allocated memory block and ensures that the contents (up to the minimum of the current and the new number of rows) remain the same.

If rows is smaller than the current number of rows, the matrix will be truncated. Otherwise, the number of rows will be retained, but there will be empty, uninitialized space at the end.

Returns the new location of the reallocated matrix and NULL on failure. If NULL is returned, the original matrix remains intact.

// Allocate an uninitialized 1-by-4 matrix.
va_matrix* mat = va_matrix_alloc(va_imatrix_type, 1, 4);
// Reserve space for up to four rows. This doesn't change row count.
va_matrix* mat2 = va_matrix_realloc(mat, 4);
if (mat2)
  mat = mat2;

// With double-precision complex numbers.
va_dcmatrix* dcmat = va_dcmatrix_alloc(1, 4);
va_dcmatrix* dcmat2 = va_dcmatrix_realloc(dcmat, 4);
if (dcmat2)
  dcmat = dcmat2;

va_matrix *va_matrix_clone(const va_matrix *matrix)

Returns a deep copy of matrix of NULL if memory allocation fails.

va_matrix *va_matrix_append_rows(va_matrix *matrix, int count)

Appends count rows to the end of matrix.

If the current capacity of the matrix is not enough to store the new rows, the matrix will be reallocated. The contents of the new rows will be unitialized.

Returns a potentially reallocated matrix or NULL on failure. If NULL is returned, matrix remains intact.

// Allocate an uninitialized Boolean 1-by-1 matrix.
va_bmatrix* bmat = va_bmatrix_alloc(1, 1);
// Make it 4-by-1
va_bmatrix* bmat2 = va_bmatrix_append_rows(bmat, 4);
if (bmat2)
  bmat = bmat2;

va_matrix *va_matrix_insert_rows(va_matrix *matrix, int index, int count)

Makes free space at the middle of matrix by moving rows from index up count rows forwards.

The contents of the new rows are unspecified.

Returns a potentially reallocated matrix or NULL on failure. If NULL is returned, matrix remains intact.

// Allocate an all-zero (false) boolean 2-by-2 matrix.
va_bmatrix* bmat = va_bmatrix_calloc(2, 2);
// Insert a row to the middle.
va_bmatrix* bmat2 = va_bmatrix_insert_rows(bmat, 1, 1);
if (bmat2)
  bmat = bmat2;

va_matrix *va_matrix_insert_columns(va_matrix *matrix, int index, int count)

Inserts count new columns at the specified index.

The contents of the new columns are unspecified.

Returns a reallocated matrix or NULL on failure. If NULL is returned, matrix remains intact.

// Allocate an all-zero (false) boolean 2-by-2 matrix.
va_bmatrix* bmat = va_bmatrix_calloc(2, 2);
// Insert a column to the middle.
va_bmatrix* bmat2 = va_bmatrix_insert_columns(bmat, 1, 1);
if (bmat2)
  bmat = bmat2;

void va_matrix_remove_rows(va_matrix *matrix, int index, int count)

Removes count rows starting at index by moving the rest of the rows backwards.

The allocated size will not be changed; a subsequent call to va_matrix_append_rows() will be a zero-cost operation.

// Allocate an all-zero integer matrix.
va_imatrix* imat = va_imatrix_calloc(3, 3);
// Remove the middle row.
va_imatrix_remove_rows(imat, 1, 1);

va_matrix *va_matrix_remove_columns(va_matrix *matrix, int index, int count)

Removes count columns starting at index by moving the rest of the columns backwards.

Returns a reallocated matrix or NULL on failure. If NULL is returned, matrix remains intact.

// Allocate an all-zero integer matrix.
va_imatrix* imat = va_imatrix_calloc(3, 3);
// Remove the middle column.
va_imatrix* imat2 = va_imatrix_remove_columns(imat, 1, 1);
if (imat2)
  imat = imat2;

va_matrix *va_matrix_resize(va_matrix *matrix, int rows, int columns)

Resizes matrix to rows-by-*columns*, retaining as much data as possible.

If the new size is bigger than the original, the initial contents of new elements will be unspecified. If the number of columns changes or the capacity of the matrix is exceeded, the matrix will be reallocated.

Returns a potentially reallocated matrix or NULL on failure. If NULL is returned, matrix remains intact.

// Allocate an all-zero integer matrix.
va_imatrix* imat = va_imatrix_calloc(3, 3);
// Make it 4-by-4. The upper 3-by-3 corner will remain zeros.
va_imatrix* imat2 = va_imatrix_resize(imat, 4, 4);
if (imat2)
  imat = imat2;

void *va_matrix_data(const va_matrix *matrix)

Returns a pointer to the first element of matrix.

// Allocate an uninitialized double matrix.
va_dmatrix* dmat = va_dmatrix_alloc(3, 3);
double* data = va_dmatrix_data(dmat);
// Set all elements to zero.
memset(data, 0, sizeof(double) * 3 * 3);

void *va_matrix_row(const va_matrix *matrix, int index)

Returns a pointer to the beginning of the row at index.

// Allocate an uninitialized double matrix.
va_dmatrix* dmat = va_dmatrix_alloc(3, 3);
double* data = va_dmatrix_row(dmat, 1);
// Set middle row to zeros.
memset(data, 0, sizeof(double) * 3);

void va_matrix_free(void *matrix)

Deallocates a matrix previously returned by va_matrix_alloc, va_matrix_calloc, va_matrix_realloc or any other function that may return a newly allocated or reallocated matrix.

This function works the same for all matrix types, but type-specific versions are also available.

va_dmatrix* dmat = va_dmatrix_alloc(3, 3);
va_dmatrix_free(dmat);
// This is equivalent:
//va_matrix_free(dmat);

size_t va_matrix_bytes(const va_matrix *matrix)

Returns the total number of bytes required for the data array of the matrix.

static inline size_t va_matrix_element_bytes(va_matrix_type type)

Returns the number of bytes an element in a matrix of the given type occupies.