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);

char *  copy_string(char * dest, const char * src, int len);
char *  append_string(char * dest, const char * src, int len);

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 returns a pointer to the array after clearing it. To set all elements to a particular value, use set_array instead.

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);

It is also possible to initialize an array from a string with numbers. The string should consist of numbers with white space inbetween. It is allowed to use commas (,) as separators, but it is not required. The function will return the array and set the parameter size to the number of elements found in the string.

float * create_array(const char * s, int & size, bool fixed_size=false);

The following example would allocate an array with three elements:

   int size;
   float * a = create_array("1.2 3.2 5.0", size)

It is possible to pass a desired size in the size parameter if fixed_size is set to true. In this case, the array will be filled with the data from the string that fits. If the string contains less data than the size, the rest of the array will be set to zero.

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. The argument decimals can contain flags that tells the function to print in a form that allows the printout to be directly copied into MATLAB. By including the flag DIM, the function will also print the size of the array. For example

   print_array("a", a, 3, 2 | MATLAB)

would print the array a in MATLAB format with two decimals. Similarily

   print_array("a", a, 3, 4 | DIM)

would print the same array with four decimals and with information about its size [3].

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

The use of arrays in Ikaros is 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);
float ***   create_matrix(int sizex, int sizey, int sizez);
float ****  create_matrix(int sizex, int sizey, int sizez, int sizet);

void     destroy_matrix(float ** m);
void     destroy_matrix(float *** m);
void     destroy_matrix(float **** m);

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);

Note that the sizes should always be the same as the allocated matrix in copy, reset and set matrix. For example, setting sizex and sizey to a smaller size in copy_matrix will not copy a submatrix.

It is also possible to initialize a two-dimensional matrix from a string. The string should consist of numbers with white space inbetween and semicolon (;) as row separator. It is allowed to use commas (,) as separators between element in a row, but it is not required. The function will return the matrix and set the parameters sizex and sizey to the number of elements found in the string. If there are unequal number of elemnts in the different rows, sizex will be set to the maximal number of elements and zeros will be stored in locations where no values are given.

float * create_matrix(const char * s, int & sizex, int & sizey, bool fixed_size=false);

The following example would allocate a matrix with 2 x 3 elements:

   int sizex, sizey;
   float ** m = create_matrix("1.2  3.2  5.0; 0.0  1.1  3.3", sizex, sizey)

It is possible to pass a desired size in the parameters sizex and sizey if fixed_size is set to true. In this case, the matrix will be filled with the data from the string that fits. If the string contains less data than the size of the matrix, the rest of the matrix will be set to zero.

The function print_matrix can be used during debugging to print the contents of a matrix. The string supplied to the function is printed as a label of the matrix. The argument decimals specifies the number of decimals to print and can also contain flags that tells the function to print in a form that allows the printout to be directly copied into MATLAB. By including the flag DIM, the function will also print the size of the matrix. For example

   print_matrix("m", m, 3, 2, 2 | MATLAB)

would print the matrix m in MATLAB format with two decimals. Similarily

   print_matrix("m", m, 3, 2, 4 | DIM)

would print the same matrix with four decimals and with information about its size [3][2].

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

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

blog comments powered by Disqus