Arrays of datasets (GNU Astronomy Utilities)

GNU Astronomy Utilities

11.3.6.3 Arrays of datasets

Gnuastro’s generic data container (gal_data_t) is a very versatile structure that can be used in many higher-level contexts. One such higher-level construct is an array of gal_data_t structures to simplify the allocation (and later cleaning) of several gal_data_ts that are related.

For example, each column in a table is usually represented by one gal_data_t (so it has its own name, data type, units, etc). A table (with many columns) can be seen as an array of gal_data_ts (when the number of columns is known a-priori). The functions below are defined to create a cleared array of data structures and to free them when none are necessary any more. These functions are declared in gnuastro/data.h which is also visible from the function names (see Gnuastro library).

Function:
gal_data_t *
gal_data_array_calloc (size_t size)

Allocate an array of gal_data_t with size elements. This function will also initialize all the values (NULL for pointers and 0 for other types). You can use gal_data_initialize to fill each element of the array afterwards. The following code snippet is one example of doing this.

size_t i;
gal_data_t *dataarr;
dataarr=gal_data_array_calloc(10);
for(i=0;i<10;++i) gal_data_initialize(&dataarr[i], ...);
...
gal_data_array_free(dataarr, 10, 1);

Function:
void
gal_data_array_free (gal_data_t *dataarr, size_t num, int free_array)

Free all the num elements within dataarr and the actual allocated array. If free_array is not zero, then the array element of all the datasets will also be freed, see Generic data container (gal_data_t).

Function:
gal_data_t **
gal_data_array_ptr_calloc (size_t size)

Allocate an array of pointers to Gnuastro’s generic data structure and initialize all pointers to NULL. This is useful when you want to allocate individual datasets later (for example with gal_data_alloc).

Function:
void
gal_data_array_ptr_free (gal_data_t **dataptr, size_t size, int free_array);

Free all the individual datasets within the elements of dataptr, then free dataptr itself (the array of pointers that was probably allocated with gal_data_array_ptr_calloc.