GNU Astronomy Utilities


Next: , Previous: , Up: Library data container   [Contents][Index]


10.3.5.2 Dataset size and 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 the size, pointers, allocation and freeing. These functions are declared in gnuastro/data.h which is also visible from the function names (see Gnuastro library).

Function:
int
gal_data_dsize_is_different (gal_data_t *first, gal_data_t *second)

Return 1 (one) if the two datasets don’t have the same size along all dimensions. This function will also return 1 when the number of dimensions of the two datasets are different.

Function:
void *
gal_data_ptr_increment (void *pointer, size_t increment, uint8_t type)

Return a pointer to an element that is increment elements ahead of pointer, assuming each element has type of type (for the type codes, see Library data types (type.h)).

When working with the array elements of gal_data_t, we are actually dealing with void * pointers. However, pointer arithmetic doesn’t apply to void *, because the system doesn’t know how many bytes there are in each element to increment the pointer respectively. This function will use the given type to calculate where the incremented element is located in memory.

Function:
size_t
gal_data_ptr_dist (void *earlier, void *later, uint8_t type)

Return the number of elements between earlier and later assuming each element has a type defined by type (for the type codes, see Library data types (type.h)).

Function:
void *
gal_data_malloc_array (uint8_t type, size_t size, const char *funcname, const char *varname)

Allocate an array of type type with size elements in RAM (for the type codes, see Library data types (type.h)). This is effectively just a wrapper around C’s malloc function but takes Gnuastro’s integer type codes and will also abort with an error if there the allocation was not successful.

When space cannot be allocated, this function will abort the program with a message containing the reason for the failure. funcname (name of the function calling this function) and varname (name of variable that needs this space) will be used in this error message if they are not NULL. In most modern compilers, you can use the generic __func__ variable for funcname. In this way, you don’t have to manually copy and paste the function name or worry about it changing later (__func__ was standardized in C99).

Function:
void *
gal_data_calloc_array (uint8_t type, size_t size), const char *funcname, const char *varname)

Similar to gal_data_malloc_array, but the space is cleared (set to 0) after allocation.

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, 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 aren’t 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 clean all the allocated spaces with gal_data_free_contents.

If array is not NULL, it will be directly copied into data->array 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 (void *array, uint8_t type, size_t ndim, size_t *dsize, struct wcsprm *wcs, int clear, size_t minmapsize, 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_free_contents (gal_data_t *data)

Free all the non-NULL pointers in gal_data_t. If data is actually a tile (data->block!=NULL, see Tessellation library (tile.h)), then tile->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.


Next: , Previous: , Up: Library data container   [Contents][Index]