GNU Astronomy Utilities



12.3.8.3 List of size_t

The size_t type is a unique type in C: as the name suggests it is defined to store sizes, or more accurately, the distances between memory locations. Hence it is always positive (an unsigned type) and it is directly related to the address-able spaces on the host system: on 32-bit and 64-bit systems it is an alias for uint32_t and uint64_t, respectively (see Numeric data types).

size_t is the default compiler type to index an array (recall that an array index in C is just a pointer increment of a given size). Since it is unsigned, it is a great type for counting (where negative is not defined), you are always sure it will never exceed the system’s (virtual) memory and since its name has the word “size” inside it, it provides a good level of documentation264. In Gnuastro, we do all counting and array indexing with this type, so this list is very handy. As discussed above, size_t maps to different types on different machines, so a portable way to print them with printf is to use C99’s %zu format.

Type (C struct): gal_list_sizet_t

A single node in a list containing a size_t value (which maps to uint32_t or uint64_t on 32-bit and 64-bit systems), see Numeric data types.

typedef struct gal_list_sizet_t
{
  size_t v;
  struct gal_list_sizet_t *next;
} gal_list_sizet_t;
Function:
void
gal_list_sizet_add (gal_list_sizet_t **list, size_t value)

Add a new node (containing value) to the top of the list of size_ts and update list. Here is one short example of initializing and adding elements to a string list:

gal_list_sizet_t *list=NULL;
gal_list_sizet_add(&list, 45493);
gal_list_sizet_add(&list, 930484);
Function:
sizet_t
gal_list_sizet_pop (gal_list_sizet_t **list)

Pop the top element of list and return the value. This function will also change list to point to the next node in the list. If *list==NULL, then this function will also return GAL_BLANK_SIZE_T (see Library blank values (blank.h)).

Function:
size_t
gal_list_sizet_number (gal_list_sizet_t *list)

Return the number of nodes in list.

Function:
size_t
gal_list_sizet_last (gal_list_sizet_t *list)

Return a pointer to the last node in list.

Function:
void
gal_list_sizet_print (gal_list_sizet_t *list)

Print the values within each node of *list on the standard output in the same order that they are stored. Each integer is printed on one line. This function is mainly good for checking/debugging your program. For program outputs, it is best to make your own implementation with a better, more user-friendly format. For example, the following code snippet. You can also modify it to print all values in one line, etc., depending on the context of your program.

size_t i=0;
gal_list_sizet_t *tmp;
for(tmp=list; tmp!=NULL; tmp=tmp->next)
  printf("Number %zu: %zu\n", ++i, tmp->v);
Function:
void
gal_list_sizet_reverse (gal_list_sizet_t **list)

Reverse the order of the list such that the top node in the list before calling this function becomes the bottom node after it.

Function:
size_t *
gal_list_sizet_to_array (gal_list_sizet_t *list, int reverse, size_t *num)

Dynamically allocate an array and fill it with the values in list. The function will return a pointer to the allocated array and put the number of elements in the array into the num pointer. If reverse has a non-zero value, the array will be filled in the inverse of the order of elements in list. This function can be useful after you have finished reading an initially unknown number of values and want to put them in an array for easy random access.

Function:
void
gal_list_sizet_free (gal_list_sizet_t *list)

Free every node in list.


Footnotes

(264)

So you know that a variable of this type is not used to store some generic state for example.