Eina_Hash in action

We are going to store some tuples into our table, that will map each name to a number. The cost to access a given number from the name should be very small, even with many entries in our table. This is the initial data:

struct _Phone_Entry {
     const char *name; // Full name.
     const char *number; // Phone number.
};
 
typedef struct _Phone_Entry Phone_Entry;
 
static Phone_Entry _start_entries[] = {
       { "Wolfgang Amadeus Mozart", "+01 23 456-78910" },
       { "Ludwig van Beethoven", "+12 34 567-89101" },
       { "Richard Georg Strauss", "+23 45 678-91012" },
       { "Heitor Villa-Lobos", "+34 56 789-10123" },
       { NULL, NULL }
}; // _start_entries

Before starting to play with the hash, let's write a callback that will be used to free the elements from it. Since we are just storing strduped strings, we just need to free them:

static void
_phone_entry_free_cb(void *data)
{
   free(data);
}

We also need a callback to iterate over the elements of the list later, so we are defining it now:

static Eina_Bool
_phone_book_foreach_cb(const Eina_Hash *phone_book EINA_UNUSED, const void *key,
                       void *data, void *fdata EINA_UNUSED)
{
   const char *name = key;
   const char *number = data;
   printf("%s: %s\n", name, number);
 
   // Return EINA_FALSE to stop this callback from being called
   return EINA_TRUE;
}

Now let's create our Eina_Hash using eina_hash_string_superfast_new :

   eina_init();
 
   phone_book = eina_hash_string_superfast_new(_phone_entry_free_cb);

Now we add the keys and data to the hash using eina_hash_add . This means that the key is copied inside the table, together with the pointer to the data (phone numbers).

   for (i = 0; _start_entries[i].name != NULL; i++)
     {
        eina_hash_add(phone_book, _start_entries[i].name,
                      strdup(_start_entries[i].number));
     }

Some basic manipulations with the hash, like finding a value given a key, deleting an entry, modifying an entry are exemplified in the following lines. Notice that the eina_hash_modify function returns the old value stored in that entry, and it needs to be freed, while the eina_hash_del function already calls our free callback:

   // Look for a specific entry and get its phone number
   phone = eina_hash_find(phone_book, entry_name);
   if (phone)
     {
        printf("Printing entry.\n");
        printf("Name: %s\n", entry_name);
        printf("Number: %s\n\n", phone);
     }
 
   // Delete this entry
   r = eina_hash_del(phone_book, entry_name, NULL);
   printf("Hash entry successfully deleted? %d\n\n", r);
 
   // Modify the pointer data of an entry and free the old one
   phone = eina_hash_modify(phone_book, "Richard Georg Strauss",
                            strdup("+23 45 111-11111"));
   free(phone);

The eina_hash_set function can be used to set a key-value entry to the table if it doesn't exist, or to modify an existent entry. It returns the old entry if it was already set, and NULL otherwise. But since it will return NULL on error too, we need to check if an error has occurred:

   // Modify or add an entry to the hash with eina_hash_set
   // Let's first add a new entry
   phone = eina_hash_set(phone_book, "Raul Seixas",
                         strdup("+55 01 234-56789"));
   if (!phone)
     {
        printf("No previous phone found for Raul Seixas. ");
        printf("Creating new entry.\n");
     }
   else
     {
        printf("Old phone for Raul Seixas was %s\n", phone);
        free(phone);
     }
 
   printf("\n");

There are different ways of iterate over the entries of a hash. Here we show two of them: using eina_hash_foreach and Eina_Iterator.

   printf("List of phones:\n");
   eina_hash_foreach(phone_book, _phone_book_foreach_cb, NULL);
   printf("\n");
 
   // Now iterate using an iterator
   printf("List of phones:\n");
   it = eina_hash_iterator_tuple_new(phone_book);
   while (eina_iterator_next(it, &data))
     {
        Eina_Hash_Tuple *t = data;
        const char *name = t->key;
        const char *number = t->data;
        printf("%s: %s\n", name, number);
     }
   eina_iterator_free(it); // Always free the iterator after its use

It's also possible to change the key for a specific entry, without having to remove the entry from the table and adding it again:

   eina_hash_move(phone_book, "Raul Seixas", "Alceu Valenca");

We can remove all the elements from the table without free the table itself:

   // Empty the phone book, but don't destroy it
   eina_hash_free_buckets(phone_book);
   printf("There are %d items in the hash.\n\n",
          eina_hash_population(phone_book));

Or free the the entire table with its content:

   eina_hash_free(phone_book);

The full code for this example can be seen here: Hash table in action