Next: Arrays of datasets, Previous: Generic data container, Up: Library data container [Contents][Index]
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).
*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.
*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.
*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)).
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).
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.
*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).
*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.
*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).
*data)Free all the non-NULL pointers in gal_data_t, then free the
actual data structure.
Next: Arrays of datasets, Previous: Generic data container, Up: Library data container [Contents][Index]
GNU Astronomy Utilities 0.5 manual, December 2017.