---

12.3.6.2 Dataset allocation ¶

Gnuastro’s main data container was defined in Generic data container (gal_data_t). The functions listed in this section describe the most basic operations on gal_data_t: those related to allocation and freeing. 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_alloc (void *array, uint8_t type, size_t ndim, size_t *dsize, struct wcsprm *wcs, int clear, size_t minmapsize, int quietmmap, char *name, char *unit, char *comment) ¶

Dynamically allocate a gal_data_t and initialize it will all the given values. See the description of gal_data_initialize and Generic data container (gal_data_t) for more information. This function will often be the most frequently used because it allocates the gal_data_t hosting all the values and initializes it. Once you are done with the dataset, be sure to clean up all the allocated spaces with gal_data_free.

Function:
void
gal_data_initialize (gal_data_t *data, void *array, uint8_t type, size_t ndim, size_t *dsize, struct wcsprm *wcs, int clear, size_t minmapsize, int quietmmap, char *name, char *unit, char *comment) ¶

Initialize the given data structure (data) with all the given values. Note that the raw input gal_data_t must already have been allocated before calling this function. For a description of each variable see Generic data container (gal_data_t). It will set the values and do the necessary allocations. If they are not NULL, all input arrays (dsize, wcs, name, unit, comment) are separately copied (allocated) by this function for usage in data, so you can safely use one value to initialize many datasets or use statically allocated variables in this function call. Once you are done with the dataset, you can free all the allocated spaces with gal_data_free_contents.

If array is not NULL, it will be directly copied into data->array (based on the total number of elements calculated from dsize) and no new space will be allocated for the array of this dataset, this has many low-level advantages and can be used to work on regions of a dataset instead of the whole allocated array (see the description under block in Generic data container (gal_data_t) for one example). If the given pointer is not the start of an allocated block of memory or it is used in multiple datasets, be sure to set it to NULL (with data->array=NULL) before cleaning up with gal_data_free_contents.

ndim may be zero. In this case no allocation will occur, data->array and data->dsize will be set to NULL and data->size will be zero. However (when necessary) dsize must not have any zero values (a dimension of length zero is not defined).

Function:
gal_data_t *
gal_data_alloc_empty (size_t ndim, size_t minmapsize, int quietmmap) ¶

Allocate an empty dataset with a certain number of dimensions, but no ’array’ component. The size element will be set to zero and the dsize array will be properly allocated (based on the number of dimensions), but all elements will be zero. This is useful in scenarios where you just need a gal_data_t for metadata.

Function:
void
gal_data_free_contents (gal_data_t *data) ¶

Free all the non-NULL pointers in gal_data_t except for next and block. All freed arrays are set to NULL. If data is actually a tile (data->block!=NULL, see Tessellation library (tile.h)), then data->array is not freed. For a complete description of gal_data_t and its contents, see Generic data container (gal_data_t).

Function:
void
gal_data_free (gal_data_t *data) ¶

Free all the non-NULL pointers in gal_data_t, then free the actual data structure.