GList, Doubly Linked List

The easiest to use are GList's. The basic GList structure is just a single node of the linked list and you can put your data into the data pointer in the GList structure. To store a linked list you just store a pointer to the first node of the list. Here is the list of functions that operate on a GList. The functions usually take in a pointer and return the new pointer of the list, since the first node could now be a different one.

To access the data from a particular GList node You look at the data member in the GList structure. So code that would create a linked list of two elements which are strdup'ed strings, and later free that list and the strings would look like:

GList *list = NULL; /*the actual list pointer*/
GList *li; /*just a temporary pointer to a node used for iterating
             over the list*/
...
/*here we add two strings to the list*/
list = g_list_append(list,g_strdup("String 1"));
list = g_list_append(list,g_strdup("String 2"));
...
/*here we loop though the list, freeing all the strings and then
  we free the list itself*/
for(li = list; li!= NULL; li = g_list_next(li)) {
        char *string = li->data;
        g_free(string);
}
g_list_free(list);

GString, Dynamically Sized String Type

Another simple to use and useful container is the GString container. It's a dynamically sized string container for the times when you don't know how large the string you will need will be. Here's a list of the most important functions.

To access the string data for use as a char *, just access the str element of the GString structure. You can actually free the GString structure without freeing this data segment. This is useful if you want to create a normal C string. The following example is a function that takes an array of integers and sprintfs them into a string and returns a char *.

char *
create_number_list(int array[], int array_len)
{
        int i;           /* the array iterator */
        GString *string; /* the GString */
        char *ret;       /* the return value */

        /* make a new GString that is empty */
        string = g_string_new("");

        /* iterate over the integer array */
        for(i=0; i<array_len; i++) {
                /* append the number to the string in parenthesis */
                g_string_sprintfa(string, "(%d)", array[i]);
        }

        /* setup the return value */
        ret = string->str;

        /* free the GString structure, but not the data */
        g_string_free(string,FALSE);

        /* return the string */
        return ret;
}

GHashTable

Though less often used then GList's and GString's. The hash table container is a very useful one. Usually by a hash table one would mean an object (in GLib's terms a gpointer) would have a string key, by which we could recall the object at a later time. GLib takes this a step further, making the key a gpointer as well, and letting you provide a hashing and a comparison function yourself. While this makes GHashTable much more flexible, it can lead to some confusion with respect to memory allocation for the keys. Let's give some important functions and deal with the details later:

To create a hash table, you pass the hash and key compare functions to g_hash_table_new. There are standard functions defined for strings (g_str_hash and g_str_equal) and others. However if you pass NULL as the hash and compare functions, you will get a direct pointer hash, where pointers will be actually themselves used as keys.

The problem of memory allocation becomes apparent when we start using string hashes. GHashTable doesn't store the string, all it stores is a pointer. Therefore, when inserting a value into the hash, you have to create a new copy of the key for that value. This is an important thing to remember as otherwise things are not going to behave really nice for you. The other problem is how to then get rid of the key. If you do a g_hash_table_remove, you give as a key a string with the same contents as the original key, but not the same memory location. After then a pointer to the original key would be lost and unless you stored a pointer to it somewhere, you just created a memory leak. What you need to do instead is to do a g_hash_table_lookup_extended first to get both the value and the original key pointer and then do the g_hash_table_remove.

The following example will make a new string hash, insert a couple of strings into it, retrieve them, and then destroy the hash and the values stored in it:

/* function we use for freeing the keys and data in the hash before
   we destroy the hash */
static void
free_key_value(gpointer key, gpointer value, gpointer user_data)
{
        g_free(key);
        g_free(value);
}

...

/* somewhere else in the code */

GHashTable *ht;

/* create a new hash table with strings as keys */
ht = g_hash_table_new(g_str_hash, g_str_equal);

/* insert a couple of strings (say colors keyed by shape) */
g_hash_table_insert(ht, g_strdup("triangle"), g_strdup("green"));
g_hash_table_insert(ht, g_strdup("square"), g_strdup("red"));
g_hash_table_insert(ht, g_strdup("circle"), g_strdup("blue"));

/* again, somewhere else in the code */
...
/* now here we wish to print out the color of a square */
char *color;

/* get the color of a square */
color = g_hash_table_lookup(ht, "square");

printf("The color of a square is: %s\n",color);

/* yet again somewhere else */
...
/* Now here we just want to destroy the hash table and free all the
 * memory associated with it. We use the free_key_value function and
 * have it run over all the values in the hash table. */
g_hash_foreach(ht, free_key_value, NULL);

/* now we can destroy the actual hash table */
g_hash_table_destroy(ht);