Adding some hashtable examples

Author: srdja

CMakeLists.txt

@@ -12,3 +12,4 @@ enable_testing()
 
 add_subdirectory(src)
 add_subdirectory(test)
+add_subdirectory(examples)

examples/CMakeLists.txt

@@ -0,0 +1,9 @@
+cmake_minimum_required(VERSION 3.5)
+
+set(CMAKE_DISABLE_IN_SOURCE_BUILD ON)
+
+set(CFLAGS "-Wall -Werror")
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${CFLAGS}")
+set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${CFLAGS}")
+
+add_subdirectory(hashtable)

examples/README.md

@@ -0,0 +1,28 @@
+cmake_minimum_required(VERSION 3.5)
+project(collectc_hashtable_examples)
+
+include_directories(${PROJECT_SOURCE_DIR}/include ${collectc_INCLUDE_DIRS})
+
+add_executable(string_keys initialization/string_keys.c)
+target_link_libraries(string_keys collectc)
+
+add_executable(custom_key_types initialization/custom_key_types.c)
+target_link_libraries(custom_key_types collectc)
+
+add_executable(pointer_keys initialization/pointer_keys.c)
+target_link_libraries(pointer_keys collectc)
+
+add_executable(configuration initialization/configuration.c)
+target_link_libraries(configuration collectc)
+
+add_executable(iterating_over_pairs operations/iterating_over_pairs.c)
+target_link_libraries(iterating_over_pairs collectc)
+
+add_executable(adding_key_value_pairs operations/adding_key_value_pairs.c)
+target_link_libraries(adding_key_value_pairs collectc)
+
+add_executable(removing_key_value_pairs operations/removing_key_value_pairs.c)
+target_link_libraries(removing_key_value_pairs collectc)
+
+add_executable(getting_info_about_the_table_and_pairs operations/getting_info_about_the_table_and_pairs.c)
+target_link_libraries(getting_info_about_the_table_and_pairs collectc)

examples/hashtable/CMakeLists.txt

@@ -0,0 +1,66 @@
+/* Example of performance tuning a table by setting it's capacity
+   and load factor. */
+
+
+#include <hashtable.h>
+
+
+int main(int argc, char **argv)
+{
+    HashTableConf config;
+    hashtable_conf_init(&config);
+
+    /* As explained in the string_key example if we don't specifically set
+     the key options they'll default to string.
+
+     ************************************************************
+
+     Set the initial capacity of the internal array. Note that
+     the value here is a power of 2. Non 2^n values can be passed,
+     but they'll be rounded to the nearest upper 2^n value for performance
+     reasons (12 would round to 16, etc.).
+
+     Note that a hashtable can hold an unlimited (limited only by
+     memory) number key/value pairs. This value is better viewed
+     not as an absolute capacity, but as a performant capacity.
+     Anything beyond this number is going to see a sharp decrease in
+     performance. Of course, by default, the table resizes before
+     this point is reached. However, this default behavior can be
+     changed by changing the load_factor. */
+    config.initial_capacity = 32;
+
+    /*
+     This value controls the rate of expansion of the internal array.
+     It is usually set between 0 and 1. Although values above 1 are valid,
+     there's little value in setting them.
+
+     The load factor represents the percentage of fullness of the internal
+     array (capacity set above) at which the internal array resize is triggered.
+     In this case, since we've set the initial capacity to 32 and the load
+     factor to 0.5, the resize will happen as soon as we add the 16th pair.
+     The rule here is capacity * load_factor, which translates to 32 * 0.5
+     in our case.
+
+     So why set this value?
+
+     By setting this value (and the capacity) we can control the performance
+     of the table. If space is abundant and we don't care about it that much,
+     we can set the load factor to a smaller value to keep the table sparsely
+     populated and thus bring the performance close to O(1) by avoiding
+     hash collisions (collision happen fairly often because of hash truncation).
+     On the other hand, if the space is a problem we can set the load factor
+     to a higher value and keep the table tightly packed at the expense of some
+     speed.
+
+     In short:
+     capacity up   + load_factor down = fast table but space wasteful
+     capacity down + load_factor up   = slow table but space conserving
+    */
+    config.load_factor      = 0.5;
+
+
+    HashTable *table;
+    hashtable_new_conf(&config, &table);
+    hashtable_destroy(table);
+    return 0;
+}

examples/hashtable/initialization/configuration.c

@@ -0,0 +1,81 @@
+/* Example of a table using the data behind the pointer as keys.
+
+   (check the pointer key example for direct pointer keys) */
+
+#include <hashtable.h>
+#include <stdio.h>
+
+
+/* Structure that we will use as a key. */
+struct Point {
+    int x;
+    int y;
+};
+
+
+/* We need to create a custom comparator function for our
+   Point structure. If keys are equal the function should
+   return 0. */
+int point_compare(const void *key1, const void *key2)
+{
+    struct Point p1 = *((struct Point*) key1);
+    struct Point p2 = *((struct Point*) key2);
+    return !(p1.x == p2.x && p1.y == p2.y);
+}
+
+
+int main(int argc, char **argv)
+{
+    /* Define the config structure (for more details check the
+       configuration example) */
+    HashTableConf config;
+
+    /* While it's not necessary, it's always a good idea to initialize the
+       config structure to default values and then override whichever
+       value we need. */
+    hashtable_conf_init(&config);
+
+    /* First we need to set the key length to match the length of
+       our Point structure. */
+    config.key_length = sizeof(struct Point);
+
+    /* Next, we set the hash function. The library provides a general
+       hash function we can use. */
+    config.hash = GENERAL_HASH;
+
+    /* Finally we need to set the key comparator function. */
+    config.key_compare = point_compare;
+
+    /* We can define a new table */
+    HashTable *table;
+
+    /* Create a new hashtable that Point structures as keys and assign to
+       *table*. The return value indicates the success or failure of the
+       operation. */
+    enum cc_stat status = hashtable_new_conf(&config, &table);
+
+    /* It's always a good idea to check whether the allocation of a new
+       structure was successful or not. */
+    if (status != CC_OK) {
+        /* Do some error handling */
+        if (status == CC_ERR_ALLOC) {
+            /* This is the only kind of error hashtable_new can return.
+               It means that the allocation has failed. */
+        }
+    }
+
+    /* ************************************************************
+      Adding keys
+    ************************************************************/
+
+    struct Point point;
+    point.x = 8;
+    point.y = 10;
+
+    /* Add a new key value pair. */
+    hashtable_add(table, (void*) &point, "foo");
+
+    /* Destroy the table structure */
+    hashtable_destroy(table);
+    return 0;
+}

examples/hashtable/initialization/custom_key_types.c

@@ -0,0 +1,81 @@
+/* An example of directly using pointers as keys. */
+
+
+#include <hashtable.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+/* In order to use pointers as keys directly as opposed to
+   the data behind the pointer, we need to define a function
+   that check for pointer equality. */
+int pointer_equality(const void *k1, const void *k2)
+{
+    return !(k1 == k2);
+}
+
+
+int main(int argc, char **argv)
+{
+    /* ************************************************************
+      Config strcture
+    ************************************************************/
+
+
+    /* Define the config structure (for more details check the
+       configuration example) */
+    HashTableConf config;
+
+    /* While it's not necessary, it's always a good idea to initialize the
+       config structure to default values and then override whichever
+       value we need. */
+    hashtable_conf_init(&config);
+
+    /* The length of our key should be equal to the length of a pointer. */
+    config.key_length  = sizeof(void*);
+
+    /* Next, we set the hash function. The library provides a hash function
+       that hashes the pointer itself rather than the data behind it. */
+    config.hash        = POINTER_HASH;
+
+    /* Finally, we set our comparator function. */
+    config.key_compare = pointer_equality;
+
+    /* ************************************************************
+       Creating a new table.
+    ************************************************************/
+
+    /* Define a new table pointer */
+    HashTable *table;
+
+    /* Create a new hashtable that accepts pointers as keys and assign to
+     *table*. The return value indicates the success or failure of the
+     operation. */
+    enum cc_stat status = hashtable_new_conf(&config, &table);
+
+    /* It's always a good idea to check whether the allocation of a new
+       structure was successful or not.*/
+    if (status != CC_OK) {
+        /* Do some error handling */
+        if (status == CC_ERR_ALLOC) {
+            /* This is the only kind of error hashtable_new can return.
+               It means that the allocation has failed. */
+        }
+    }
+
+    /* ************************************************************
+       Adding keys
+    ************************************************************/
+
+    /* We can now add pointer keys to our table. */
+    void *pointer = malloc(16);
+    hashtable_add(table, (void*) pointer, "bar");
+
+    /* We can even hackishly use it for direct integer keys. */
+    uintptr_t number  = 23123;
+    hashtable_add(table, (void*) number, "foo");
+
+    /* After we're done using the table, we can destroy it with. This
+       only destroys the structure, not the actual data inside of it. */
+    hashtable_destroy(table);
+    return 0;
+}

examples/hashtable/initialization/pointer_keys.c

@@ -0,0 +1,70 @@
+/* An example of creating a hash table that works with string keys. */
+
+#include <hashtable.h>
+
+
+int main(int argc, char **argv)
+{
+    /* Define a new table pointer */
+    HashTable *string_table;
+
+    /* Create a new hashtable that accepts strings as keys and assign to
+     *string_pointer*. The return value indicates success or failure
+     of the operation.
+
+     A thing to note here is that when hashtable_new is used and no
+     additional configuration is passed, the default behavior is to
+     create a string key table.
+
+     This can be changed by using a different constructor that accepts
+     a configuration structure as a parameter. (more details below) */
+    enum cc_stat status = hashtable_new(&string_table);
+
+    /* It's always a good idea to check whether the allocation of a new
+       structure was successful or not. */
+    if (status != CC_OK) {
+        /* Do some error handling */
+
+        if (status == CC_ERR_ALLOC) {
+            /* This is the only kind of error hashtable_new can return.
+               It means that the allocation has failed. */
+        }
+    }
+
+    /* After we're done using the table, we can destroy it with. This
+       only destroys the structure, not the actual data inside of it. */
+    hashtable_destroy(string_table);
+
+    /************************************************************
+     Alternatively a string key table can be constructed using the
+     config structure
+    ************************************************************/
+
+    /* Define the config structure (for more details check the
+       configuration example) */
+    HashTableConf config;
+
+    /* While it's not necessary, it's always a good idea to initialize the
+       config structure to default values and then override whichever
+       value we need. */
+    hashtable_conf_init(&config);
+
+    /* The hash function needs to know the length of the key and since we
+       are using strings, the key length will be variable. */
+    config.key_length = KEY_LENGTH_VARIABLE;
+
+    /* Next, we set the hash function. The library already provides a
+       string hashing function. */
+    config.hash = STRING_HASH;
+
+    /* Finally, we need to set the key comparator function. The library
+       provides a default comparator. */
+    config.key_compare = CC_CMP_STRING;
+
+    /* Now we can create a new table described by the config structure */
+    status = hashtable_new_conf(&config, &string_table);
+
+
+    hashtable_destroy(string_table);
+    return 0;
+}

examples/hashtable/initialization/string_keys.c

@@ -0,0 +1,22 @@
+#include <hashtable.h>
+
+
+int main(int argc, char **argv)
+{
+    /* Make a new string key table */
+    HashTable *table;
+    hashtable_new(&table);
+
+    /* Assign value "one" to key "1" inside the table "table" */
+    enum cc_stat status = hashtable_add(table, (void*) "1", (void*) "one");
+
+    /* Checking the status of the operation is alwasy a good idea since
+       memory allocation can fail (lack of space, etc.). */
+    if (status == CC_ERR_ALLOC) {
+        /* Internal allocation error. This is the only type of error
+           hashtable_add can return. If everything went well CC_OK is
+           returned instead. */
+    }
+
+    hashtable_destroy(table);
+}