dmlfw_mat_string.h File Reference

Core string matrix types and utilities. More...

#include <dmlfw_types.h>

Include dependency graph for dmlfw_mat_string.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

typedef struct __dmlfw_mat_string	dmlfw_mat_string
	Opaque structure representing a string matrix.
void	dmlfw_mat_string_copy (dmlfw_mat_string *target, dmlfw_mat_string *source, index_t target_row_index, index_t target_column_index, index_t source_from_row_index, index_t source_from_column_index, index_t source_to_row_index, index_t source_to_column_index)
	Copies a submatrix region from source to target matrix.
dmlfw_mat_string *	dmlfw_mat_string_create_new (dimension_t rows, dimension_t columns)
	Creates a new string matrix with specified rows and columns.
dmlfw_mat_string *	dmlfw_mat_string_delete_columns (dmlfw_mat_string *matrix, index_t *indexes, dimension_t indexes_size, dmlfw_mat_string *new_matrix)
	Deletes specified columns from the matrix.
void	dmlfw_mat_string_destroy (dmlfw_mat_string *matrix)
	Destroys a string matrix and frees all allocated memory.
dmlfw_mat_string *	dmlfw_mat_string_from_csv (const char *csv_file_name, dmlfw_mat_string *matrix, dmlfw_row_vec_string **header)
	Loads a matrix and header from a CSV file.
void	dmlfw_mat_string_get (dmlfw_mat_string *matrix, index_t row, index_t column, char **string)
	Retrieves the string at specified row and column.
void	dmlfw_mat_string_get_dimensions (dmlfw_mat_string *matrix, dimension_t *rows, dimension_t *columns)
	Retrieves dimensions of the string matrix.
void	dmlfw_mat_string_set (dmlfw_mat_string *matrix, index_t row, index_t column, char *string)
	Sets the string at specified row and column.
dmlfw_mat_string *	dmlfw_mat_string_shuffle (dmlfw_mat_string *matrix, uint8_t how_many_times_to_shuffle, dmlfw_mat_string *shuffled_matrix)
	Shuffles rows of the string matrix.
void	dmlfw_mat_string_to_csv (dmlfw_mat_string *matrix, const char *csv_file_name, dmlfw_row_vec_string *header)
	Saves a string matrix and header to a CSV file.
dmlfw_mat_string *	dmlfw_mat_string_transpose (dmlfw_mat_string *matrix, dmlfw_mat_string *transposed_matrix)
	Transposes a string matrix.

Detailed Description

Core string matrix types and utilities.

Version

1.0

Date

2025-09-25

This header defines opaque matrix structures specialized for string data. It provides APIs for creation, destruction, element access and mutation, CSV import/export, matrix transpose, shuffle, copy, and column deletion.

Error Handling:

All functions report errors via the centralized error API. Use dmlfw_error() to check for errors after calls. dmlfw_get_error_string() and dmlfw_get_debug_string() provide error information.

Ownership:

Functions returning new matrix pointers transfer ownership to the caller, who is responsible for freeing with dmlfw_mat_string_destroy().

Indexing Notes:

All indices are zero-based.

Typedef Documentation

dmlfw_mat_string

typedef struct __dmlfw_mat_string dmlfw_mat_string

Opaque structure representing a string matrix.

The internal representation is hidden. Use the provided API functions to create, manipulate, and destroy instances.

Function Documentation

dmlfw_mat_string_copy()

void dmlfw_mat_string_copy	(	dmlfw_mat_string *	target,
		dmlfw_mat_string *	source,
		index_t	target_row_index,
		index_t	target_column_index,
		index_t	source_from_row_index,
		index_t	source_from_column_index,
		index_t	source_to_row_index,
		index_t	source_to_column_index
	)

Copies a submatrix region from source to target matrix.

Parameters

target	[in,out] Destination matrix (non-NULL).
source	[in] Source matrix (non-NULL).
target_row_index	[in] Start row index in target.
target_column_index	[in] Start column index in target.
source_from_row_index	[in] Starting row index in source.
source_from_column_index	[in] Starting column index in source.
source_to_row_index	[in] Ending row index in source.
source_to_column_index	[in] Ending column index in source.

See also

dmlfw_mat_string_transpose

Usage example:

dmlfw_mat_string_copy(dest, src, 0, 0, 1, 1, 3, 3);
if (dmlfw_error()) {
    dmlfw_get_error_string(err, sizeof(err));
    dmlfw_get_debug_string(dbg, sizeof(dbg));
    printf("Error copying matrix: %s\nDebug info: %s\n", err, dbg);
    return EXIT_FAILURE;
}

dmlfw_mat_string_create_new()

dmlfw_mat_string * dmlfw_mat_string_create_new	(	dimension_t	rows,
		dimension_t	columns
	)

Creates a new string matrix with specified rows and columns.

Parameters

rows	[in] Number of rows (must be > 0).
columns	[in] Number of columns (must be > 0).

Returns

Pointer to new matrix or NULL on allocation failure or invalid args.

See also

dmlfw_mat_string_destroy

Note

Caller must destroy with dmlfw_mat_string_destroy().

Usage example:

char err[512], dbg[512];
dmlfw_mat_string *mat = dmlfw_mat_string_create_new(5, 4);
if (dmlfw_error()) {
    dmlfw_get_error_string(err, sizeof(err));
    dmlfw_get_debug_string(dbg, sizeof(dbg));
    printf("Create failed: %s\nDebug: %s\n", err, dbg);
    return EXIT_FAILURE;
}

Examples

example_mat_string.c.

dmlfw_mat_string_delete_columns()

dmlfw_mat_string * dmlfw_mat_string_delete_columns	(	dmlfw_mat_string *	matrix,
		index_t *	indexes,
		dimension_t	indexes_size,
		dmlfw_mat_string *	new_matrix
	)

Deletes specified columns from the matrix.

Parameters

matrix	[in] Source matrix (non-NULL).
indexes	[in] Array of zero-based column indexes to delete.
indexes_size	[in] Number of indexes to delete.
new_matrix	[in,out] Optional matrix container for result, or NULL.

Returns

Pointer to new matrix after deletion, or NULL on error.

See also

dmlfw_mat_string_clone

Usage example:

index_t cols_to_delete[] = {1,3};
dmlfw_mat_string *reduced = dmlfw_mat_string_delete_columns(mat, cols_to_delete, 2, NULL);
if (dmlfw_error()) {
    dmlfw_get_error_string(err, sizeof(err));
    dmlfw_get_debug_string(dbg, sizeof(dbg));
    printf("Failed to delete column at index 2 from matrix: %s\nDebug info: %s\n", err, dbg);
    return EXIT_FAILURE;
}
dmlfw_mat_string_destroy(reduced);

dmlfw_mat_string_destroy()

void dmlfw_mat_string_destroy

(

dmlfw_mat_string *

matrix

)

Destroys a string matrix and frees all allocated memory.

Parameters

matrix

[in] Pointer to matrix, or NULL (no-op).

See also

dmlfw_mat_string_create_new

Usage example:

dmlfw_mat_string_destroy(mat);

Examples

example_mat_string.c.

dmlfw_mat_string_from_csv()

dmlfw_mat_string * dmlfw_mat_string_from_csv	(	const char *	csv_file_name,
		dmlfw_mat_string *	matrix,
		dmlfw_row_vec_string **	header
	)

Loads a matrix and header from a CSV file.

Parameters

csv_file_name	[in] CSV file path (non-NULL).
matrix	[in,out] Optional matrix to reuse or NULL.
header	[out] Pointer to receive the newly allocated header row vector.

Returns

Pointer to loaded matrix or NULL on error.

See also

dmlfw_mat_string_to_csv

Note

Caller must destroy returned matrix and header.

Header is always a row vector.

Usage example:

char err[512], dbg[512];
dmlfw_mat_string *mat = NULL;
dmlfw_row_vec_string *header = NULL;
mat = dmlfw_mat_string_from_csv("data.csv", NULL, &header);
if (dmlfw_error()) {
    dmlfw_get_error_string(err, sizeof(err));
    dmlfw_get_debug_string(dbg, sizeof(dbg));
    printf("Load failed: %s\nDebug: %s\n", err, dbg);
    return EXIT_FAILURE;
}
dmlfw_mat_string_destroy(mat);
dmlfw_row_vec_string_destroy(header);

dmlfw_mat_string_get()

void dmlfw_mat_string_get	(	dmlfw_mat_string *	matrix,
		index_t	row,
		index_t	column,
		char **	string
	)

Retrieves the string at specified row and column.

Parameters

matrix	[in] Matrix (non-NULL).
row	[in] Zero-based row index.
column	[in] Zero-based column index.
string	[out] Allocation pointer to receive string copy (must not be NULL).

See also

dmlfw_mat_string_set

Note

Returned string must be freed by caller.

Usage example:

char err[512], dbg[512];
char *str = NULL;
dmlfw_mat_string_get(mat, 0, 0, &str);
if (dmlfw_error()) {
    dmlfw_get_error_string(err, sizeof(err));
    dmlfw_get_debug_string(dbg, sizeof(dbg));
    printf("Failed to retrieve value from (1,2) : %s\nDebug info: %s\n", err, dbg);
    return EXIT_FAILURE;  
} else {
    printf("Value at (0,0): %s\n", str);
    free(str);
}

Examples

example_mat_string.c.

dmlfw_mat_string_get_dimensions()

void dmlfw_mat_string_get_dimensions	(	dmlfw_mat_string *	matrix,
		dimension_t *	rows,
		dimension_t *	columns
	)

Retrieves dimensions of the string matrix.

Parameters

matrix	[in] Matrix (non-NULL).
rows	[out] Pointer to receive row count (non-NULL).
columns	[out] Pointer to receive column count (non-NULL).

See also

dmlfw_mat_string_create_new

Usage example:

dimension_t rows, cols;
dmlfw_mat_string_get_dimensions(mat, &rows, &cols);

dmlfw_mat_string_set()

void dmlfw_mat_string_set	(	dmlfw_mat_string *	matrix,
		index_t	row,
		index_t	column,
		char *	string
	)

Sets the string at specified row and column.

Parameters

matrix	[in,out] Matrix (non-NULL).
row	[in] Zero-based row index.
column	[in] Zero-based column index.
string	[in] String value to copy into matrix (non-NULL).

See also

dmlfw_mat_string_get

Usage example:

char err[512], dbg[512];
dmlfw_mat_string_set(mat, 0, 0, "example");
if (dmlfw_error()) {
    dmlfw_get_error_string(err, sizeof(err));
    dmlfw_get_debug_string(dbg, sizeof(dbg));
    printf("Failed to set value at (1,2) : %s\nDebug info: %s\n", err, dbg);
    return EXIT_FAILURE;
}

Examples

example_mat_string.c.

dmlfw_mat_string_shuffle()

dmlfw_mat_string * dmlfw_mat_string_shuffle	(	dmlfw_mat_string *	matrix,
		uint8_t	how_many_times_to_shuffle,
		dmlfw_mat_string *	shuffled_matrix
	)

Shuffles rows of the string matrix.

Parameters

matrix	[in] Matrix to shuffle (non-NULL).
how_many_times_to_shuffle	[in] Number of shuffle iterations.
shuffled_matrix	[in,out] Optional matrix container for result, or NULL.

Returns

Pointer to shuffled matrix or NULL on error.

See also

dmlfw_mat_string_clone

Usage example:

dmlfw_mat_string *shuffled = dmlfw_mat_string_shuffle(mat, 10, NULL);
if (dmlfw_error()) {
    dmlfw_get_error_string(err, sizeof(err));
    dmlfw_get_debug_string(dbg, sizeof(dbg));
    printf("Error shuffling matrix: %s\nDebug info: %s\n", err, dbg);
    return EXIT_FAILURE;
}
dmlfw_mat_string_destroy(shuffled);

dmlfw_mat_string_to_csv()

void dmlfw_mat_string_to_csv	(	dmlfw_mat_string *	matrix,
		const char *	csv_file_name,
		dmlfw_row_vec_string *	header
	)

Saves a string matrix and header to a CSV file.

Parameters

matrix	[in] Matrix to save (non-NULL).
csv_file_name	[in] Output CSV file path (non-NULL).
header	[in] Header row vector (non-NULL).

See also

dmlfw_mat_string_from_csv

Note

File will be overwritten if it exists.

Usage example:

char err[512], dbg[512];
dmlfw_mat_string_to_csv(mat, "out.csv", header);
if (dmlfw_error()) {
    dmlfw_get_error_string(err, sizeof(err));
    dmlfw_get_debug_string(dbg, sizeof(dbg));
    printf("Error exporting matrix: %s\nDebug: %s\n", err, dbg);
    return EXIT_FAILURE;
}

dmlfw_mat_string_transpose()

dmlfw_mat_string * dmlfw_mat_string_transpose	(	dmlfw_mat_string *	matrix,
		dmlfw_mat_string *	transposed_matrix
	)

Transposes a string matrix.

Parameters

matrix	[in] Matrix to transpose (non-NULL).
transposed_matrix	[in,out] Optional matrix container to receive transpose, or NULL.

Returns

Pointer to transposed matrix or NULL on error.

Usage example:

dmlfw_mat_string *transposed = dmlfw_mat_string_transpose(mat, NULL);
if (dmlfw_error()) {
    dmlfw_get_error_string(err, sizeof(err));
    dmlfw_get_debug_string(dbg, sizeof(dbg));
    printf("Error transposing matrix: %s\nDebug info: %s\n", err, dbg);
    return EXIT_FAILURE;
}
dmlfw_mat_string_destroy(transposed);