---

12.3.8.1 List of strings

Probably one of the most common lists you will be using are lists of strings. They are the best tools when you are reading the user’s inputs, or when adding comments to the output files. Below you can see Gnuastro’s string list type and several functions to help in adding, removing/popping, reversing and freeing the list.

Type (C struct): gal_list_str_t ¶

A single node in a list containing a string of characters.

typedef struct gal_list_str_t
{
  char *v;
  struct gal_list_str_t *next;
} gal_list_str_t;

Function:
void
gal_list_str_add (gal_list_str_t **list, char *value, int allocate) ¶

Add a new node to the list of strings (list) and update it. The new node will contain the string value. If allocate is not zero, space will be allocated specifically for the string of the new node and the contents of value will be copied into it. This can be useful when your string may be changed later in the program, but you want your list to remain. Here is one short/simple example of initializing and adding elements to a string list:

gal_list_str_t *strlist=NULL;
gal_list_str_add(&strlist, "bottom of list.");
gal_list_str_add(&strlist, "second last element of list.");

Function:
char *
gal_list_str_pop (gal_list_str_t **list) ¶

Pop the top element of list, change list to point to the next node in the list, and return the string that was in the popped node. If *list==NULL, then this function will also return a NULL pointer.

Function:
size_t
gal_list_str_number (gal_list_str_t *list) ¶

Return the number of nodes in list.

Function:
gal_list_str_t *
gal_list_str_last (gal_list_str_t *list) ¶

Return a pointer to the last node in list.

Function:
void
gal_list_str_print (gal_list_str_t *list) ¶

Print the strings within each node of *list on the standard output in the same order that they are stored. Each string 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.

size_t i;
gal_list_str_t *tmp;
for(tmp=list; tmp!=NULL; tmp=tmp->next)
  printf("String %zu: %s\n", i, tmp->v);

Function:
void
gal_list_str_reverse (gal_list_str_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:
void
gal_list_str_free (gal_list_str_t *list, int freevalue) ¶

Free every node in list. If freevalue is not zero, also free the string within the nodes.

Function:
gal_list_str_t *
gal_list_str_extract (char *string) ¶

Extract space-separated components of the input string. If any space element should be kept (and not considered as a delimiter between two tokens), precede it with a back-slash (\).

Function:
char *
gal_list_str_cat (gal_list_str_t *list) ¶

Concatenate (append) the input list of strings into a single space-separated string. The space for the output string is allocated by this function and should be freed when you have finished with it.

If there is any SPACE characters in any of the elements, a back-slash (\) will be printed before the SPACE character. This is necessary, otherwise, a function like gal_list_str_extract will not be able to extract the elements back into separate elements in a list.