Matrix

Matrix

Macros

#define KUVIO_MATRIX_DECL(TYPENAME)

Enumerations

enum kuvio_matrix_type

Functions

kuvio_matrix* kuvio_matrix_alloc(kuvio_matrix_type type, int rows, int columns)
kuvio_matrix* kuvio_matrix_calloc(kuvio_matrix_type type, int rows, int columns)
kuvio_matrix* kuvio_matrix_realloc(kuvio_matrix* matrix, int rows)
kuvio_matrix* kuvio_matrix_append_rows(kuvio_matrix* matrix, int count)
kuvio_matrix* kuvio_matrix_insert_rows(kuvio_matrix* matrix, int index, int count)
kuvio_matrix* kuvio_matrix_insert_columns(kuvio_matrix* matrix, int index, int count)
void kuvio_matrix_remove_rows(kuvio_matrix* matrix, int index, int count)
kuvio_matrix* kuvio_matrix_remove_columns(kuvio_matrix* matrix, int index, int count)
kuvio_matrix* kuvio_matrix_resize(kuvio_matrix* matrix, int rows, int columns)
void* kuvio_matrix_data(const kuvio_matrix* matrix)
void* kuvio_matrix_row(const kuvio_matrix* matrix, int index)
void kuvio_matrix_free(void* matrix)

Variables

kuvio_matrix

Macro Definition Documentation

#define KUVIO_MATRIX_DECL( TYPENAME)
Value:
typedef struct TYPENAME \
{ \
kuvio_matrix_type type; \
int32_t columns; \
int32_t rows; \
int32_t capacity; \
kuvio_refcount ref_count; \
int32_t padding; \
} 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 kuvio_matrix. Type-specific matrix implementations are named according to kuvio_matrix_type:

  • int: kuvio_imatrix
  • float: kuvio_fmatrix
  • double: kuvio_dmatrix
  • kuvio_fcomplex: kuvio_fcmatrix
  • kuvio_dcomplex: kuvio_dcmatrix
  • kuvio_real: kuvio_rmatrix
  • kuvio_rcomplex: kuvio_rcmatrix

In addition to the generic functions such as kuvio_matrix_alloc, there are specialized versions for each matrix type (e.g. kuvio_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 kuvio_matrix_data function to get a pointer to it. The specialized versions such as kuvio_dmatrix_data return a typed pointer.

Enumeration Type Documentation

Matrix types.

Function Documentation

kuvio_matrix* kuvio_matrix_alloc(kuvio_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.
kuvio_matrix* mat = kuvio_matrix_alloc(kuvio_imatrix_type, 4, 4);
// Same, but typed.
kuvio_imatrix* imat = (kuvio_imatrix*)kuvio_matrix_alloc(kuvio_imatrix_type, 4, 4);
// Still same, but easier.
kuvio_imatrix* imat2 = kuvio_imatrix_alloc(4, 4);
// Floating-point elements.
kuvio_fmatrix* fmat = kuvio_fmatrix_alloc(4, 4);
kuvio_matrix* kuvio_matrix_append_rows(kuvio_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.
kuvio_bmatrix* bmat = kuvio_bmatrix_alloc(1, 1);
// Make it 4-by-1
kuvio_bmatrix* bmat2 = kuvio_bmatrix_append_rows(bmat, 4);
if (bmat2)
bmat = bmat2;
kuvio_matrix* kuvio_matrix_calloc(kuvio_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.
kuvio_matrix* mat = kuvio_matrix_calloc(kuvio_imatrix_type, 4, 4);
// Double precision
kuvio_dmatrix* dmat = kuvio_dmatrix_calloc(4, 4);
void* kuvio_matrix_data(const kuvio_matrix* matrix)

Returns a pointer to the first element of matrix.

// Allocate an uninitialized double matrix.
kuvio_dmatrix* dmat = kuvio_dmatrix_alloc(3, 3);
double* data = kuvio_dmatrix_data(dmat);
// Set all elements to zero.
memset(data, 0, sizeof(double) * 3 * 3);
void kuvio_matrix_free(void* matrix)

Deallocates a matrix previously returned by kuvio_matrix_alloc, kuvio_matrix_calloc, kuvio_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.

kuvio_dmatrix* dmat = kuvio_dmatrix_alloc(3, 3);
kuvio_dmatrix_free(dmat);
// This is equivalent:
//kuvio_matrix_free(dmat);
kuvio_matrix* kuvio_matrix_insert_columns(kuvio_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.
kuvio_bmatrix* bmat = kuvio_bmatrix_calloc(2, 2);
// Insert a column to the middle.
kuvio_bmatrix* bmat2 = kuvio_bmatrix_insert_columns(bmat, 1, 1);
if (bmat2)
bmat = bmat2;
kuvio_matrix* kuvio_matrix_insert_rows(kuvio_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.
kuvio_bmatrix* bmat = kuvio_bmatrix_calloc(2, 2);
// Insert a row to the middle.
kuvio_bmatrix* bmat2 = kuvio_bmatrix_insert_rows(bmat, 1, 1);
if (bmat2)
bmat = bmat2;
kuvio_matrix* kuvio_matrix_realloc(kuvio_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.
kuvio_matrix* mat = kuvio_matrix_alloc(kuvio_imatrix_type, 1, 4);
// Reserve space for up to four rows. This doesn't change row count.
kuvio_matrix* mat2 = kuvio_matrix_realloc(mat, 4);
if (mat2)
mat = mat2;
// With double-precision complex numbers.
kuvio_dcmatrix* dcmat = kuvio_dcmatrix_alloc(1, 4);
kuvio_dcmatrix* dcmat2 = kuvio_dcmatrix_realloc(dcmat, 4);
if (dcmat2)
dcmat = dcmat2;
kuvio_matrix* kuvio_matrix_remove_columns(kuvio_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.
kuvio_imatrix* imat = kuvio_imatrix_calloc(3, 3);
// Remove the middle column.
kuvio_imatrix* imat2 = kuvio_imatrix_remove_columns(imat, 1, 1);
if (imat2)
imat = imat2;
void kuvio_matrix_remove_rows(kuvio_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 kuvio_matrix_append_rows() will be a zero-cost operation.

// Allocate an all-zero integer matrix.
kuvio_imatrix* imat = kuvio_imatrix_calloc(3, 3);
// Remove the middle row.
kuvio_imatrix_remove_rows(imat, 1, 1);
kuvio_matrix* kuvio_matrix_resize(kuvio_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.
kuvio_imatrix* imat = kuvio_imatrix_calloc(3, 3);
// Make it 4-by-4. The upper 3-by-3 corner will remain zeros.
kuvio_imatrix* imat2 = kuvio_imatrix_resize(imat, 4, 4);
if (imat2)
imat = imat2;
void* kuvio_matrix_row(const kuvio_matrix* matrix, int index )

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

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