Ikaros Utility Functions

This document describes the utility functions in IKAROS_Utils.h. The utility function are used to allocate, deallocate and manipulate stings, arrays and matrices and related functions. These functions are automatically included in all modules through the file IKAROS.h. There is thus never any need to explicitly include IKAROS_Utilities.h.

String Functions

The function create_string allocates memory for a string and copies the string c to it. When the string is no longer needed, it should be deallocated using the function destroy_string.

It is also possible to create a string using a formatting string together with a number of arguments in the same way as in the printf function. This is the role of the function create_formatted_string.

The tring functions also include the function equal_strings that tests two strings for equality. This function differs from the standard library functions in that NULL is an acceptable string value which matches itself but is different from an empty string. This is very useful when string values need to be compared since it avoids the need to test for NULL before the comparison. 

char *	create_string(char * c);
char *	create_formatted_string(char * format, ...);
void    destroy_string(char *c);
bool    equal_strings(const char * a, const char * b);

Array Functions

To work with arrays that are not allocated by the kernel, a number of utility functions are available. The functions create_array and destroy_array are self-explanatory. The function copy array copies the array to the already existing array r, which should be large enough to include size elements. A pointer to the array r is returned for convenience.

There are two functions to manipulate the contents of an array. To set all elements to zero, use reset_array which return a potinter to the array after clearing it. To set all elements to a particular value, use set_array instead.

Finally, the function print_array can be used during debugging to print the contents of an array. The string supplied to the function is printed as a label of the array. 

float *	create_array(int size);
void    destroy_array(float * a);

float *	copy_array(float * r, float * a, int size);

float *	reset_array(float * a, int size);
float *	set_array(float * a, float v, int size);

void    print_array(char * name, float * a, int size);

The use of arrays in Ikaros are further described in the article Ikaros Data Structures.

Matrix Functions

The functions for matrices are similar to those for arrays expect that they take two size arguments. Note that in the calls the number of columns (sizex) comes before the number of rows (sizey), which is the reverse of the way elements in a matrix are accessed, that is m[y][x].

The matrices allocated using the functions below are compatible with all Ikaros functions include the math library. This is not always the case if the matrices are allocated in some other way. 

float ** create_matrix(int sizex, int sizey);
void     destroy_matrix(float ** a);

float ** copy_matrix(float ** r, float ** a, int sizex, int sizey);

float ** reset_matrix(float ** m, int sizex, int sizey);
float ** set_matrix(float ** m, float v, int sizex, int sizey);

void     print_matrix(char * name, float ** m, int sizex, int sizey);

The use of matrices in Ikaros are further described in the article Ikaros Data Structures.

Backward Compatibility

Earlier versions of Ikaros included a number of functions called CreateArray etc. These were removed in version 1.0.0 and are not compatible with the functions described above. In particular, the order of the arguments to CreatArray and create_matrix are not the same. If you update old modules to version 1.0, you need to replace the old functions with the ones above.