Updates tommy lib.

tommyarray.h

@@ -32,10 +32,9 @@
  *
  * The resize involve an allocation of a new array segment, without reallocating
  * the already allocated memory, and then not increasing the heap fragmentation.
+ * This means that the address of the allocated segments never change.
  *
  * Allocated segments grow in size exponentially.
- *
- * This means that the address of the allocated segments never change.
  */
 
 #ifndef __TOMMYARRAY_H

tommyarrayblk.h

@@ -32,10 +32,9 @@
  *
  * The resize involve an allocation of a new array block, without reallocating
  * the already allocated memory, and then not increasing the heap fragmentation.
- *
- * Allocated blocks are always of the same size.
- *
  * This means that the address of the allocated blocks never change.
+ *
+ * Allocated blocks are always of the same fixed size of 64 KiB.
  */
 
 #ifndef __TOMMYARRAYBLK_H

tommyhashdyn.c

@@ -162,7 +162,7 @@ void* tommy_hashdyn_remove_existing(tommy_hashdyn* hashdyn, tommy_hashdyn_node*
 	return node->data;
 }
 
-void* tommy_hashdyn_remove(tommy_hashdyn* hashdyn, tommy_compare_func* cmp, const void* cmp_arg, tommy_hash_t hash)
+void* tommy_hashdyn_remove(tommy_hashdyn* hashdyn, tommy_search_func* cmp, const void* cmp_arg, tommy_hash_t hash)
 {
 	unsigned pos = hash % hashdyn->bucket_max;
 	tommy_hashdyn_node* i = hashdyn->bucket[pos];

tommyhashdyn.h

@@ -78,9 +78,10 @@
  * \code
  * int compare(const void* arg, const void* obj)
  * {
- *     return (*(const unsigned*)arg != ((const struct object*)obj)->value;
+ *     return *(const int*)arg != ((const struct object*)obj)->value;
  * }
  *
+ * int value_to_find = 1; 
  * struct object* obj = tommy_hashdyn_search(&hashdyn, compare, &value_to_find, tommy_inthash_u32(value_to_find));
  * if (!obj) {
  *     // not found
@@ -95,6 +96,7 @@
  * different keys.
  *
  * \code
+ * int value_to_find = 1; 
  * tommy_node* i = tommy_hashdyn_bucket(&hashdyn, tommy_inthash_u32(value_to_find));
  * while (i) {
  *     struct object* obj = i->data; // gets the object pointer
@@ -188,7 +190,7 @@ void tommy_hashdyn_insert(tommy_hashdyn* hashdyn, tommy_hashdyn_node* node, void
  * \param hash Hash of the element to find and remove.
  * \return The removed element, or 0 if not found.
  */
-void* tommy_hashdyn_remove(tommy_hashdyn* hashdyn, tommy_compare_func* cmp, const void* cmp_arg, tommy_hash_t hash);
+void* tommy_hashdyn_remove(tommy_hashdyn* hashdyn, tommy_search_func* cmp, const void* cmp_arg, tommy_hash_t hash);
 
 /**
  * Gets the bucket of the specified hash.
@@ -213,7 +215,7 @@ tommy_inline tommy_hashdyn_node* tommy_hashdyn_bucket(tommy_hashdyn* hashdyn, to
  * \param hash Hash of the element to find.
  * \return The first element found, or 0 if none.
  */
-tommy_inline void* tommy_hashdyn_search(tommy_hashdyn* hashdyn, tommy_compare_func* cmp, const void* cmp_arg, tommy_hash_t hash)
+tommy_inline void* tommy_hashdyn_search(tommy_hashdyn* hashdyn, tommy_search_func* cmp, const void* cmp_arg, tommy_hash_t hash)
 {
 	tommy_hashdyn_node* i = tommy_hashdyn_bucket(hashdyn, hash);
 	while (i) {

tommylist.h

@@ -293,6 +293,8 @@ void tommy_list_concat(tommy_list* first, tommy_list* second);
  * Sorts a list.
  * It's a stable merge sort with O(N*log(N)) worst complexity.
  * It's faster on degenerated cases like partially ordered lists.
+ * \param cmp Compare function called with two elements.
+ * The function should return <0 if the first element is less than the second, == 0 if equal, and > 0 if greather.
  */
 void tommy_list_sort(tommy_list* list, tommy_compare_func* cmp);
 

tommytypes.h

@@ -187,19 +187,83 @@ typedef struct tommy_node_struct {
 
 /**
  * Compare function for elements.
+ * \param obj_a Pointer at the first object to compare.
+ * \param obj_b Pointer at the second object to compare.
+ * \return <0 if the first element is less than the second, ==0 equal, >0 if greather.
+ *
+ * This function is like the C strcmp().
+ *
+ * \code
+ * struct object {
+ *     tommy_node node;
+ *     int value;
+ * };
+ *
+ * int compare(const void* obj_a, const void* obj_b)
+ * {
+ *     if (((const struct object*)obj_a)->value < ((const struct object*)obj_b)->value)
+ *         return -1;
+ *     if (((const struct object*)obj_a)->value > ((const struct object*)obj_b)->value)
+ *         return 1;
+ *     return 0;
+ * }
+ *
+ * tommy_list_sort(&list, compare);
+ * \endcode
+ *
  */
-typedef int tommy_compare_func(const void* void_a, const void* void_b);
+typedef int tommy_compare_func(const void* obj_a, const void* obj_b);
+
+/**
+ * Search function for elements.
+ * \param arg Pointer at the value to search.
+ * \param obj Pointer at the object to compare to.
+ * \return ==0 if the value matches the element. != 0 if different.
+ *
+ * Note that the first argument is a pointer to the value to search and
+ * the second one is a pointer to the object to compare.
+ * They are pointers of two different types.
+ *
+ * \code
+ * struct object {
+ *     tommy_node node;
+ *     int value;
+ * };
+ *
+ * int compare(const void* arg, const void* obj)
+ * {
+ *     return *(const int*)arg != ((const struct object*)obj)->value;
+ * }
+ *
+ * int value_to_find = 1; 
+ * struct object* obj = tommy_hashtable_search(&hashtable, compare, &value_to_find, tommy_inthash_u32(value_to_find));
+ * if (!obj) {
+ *     // not found
+ * } else {
+ *     // found
+ * }
+ * \endcode 
+ *
+ */
+typedef int tommy_search_func(const void* arg, const void* obj);
 
 /**
  * Foreach function.
+ * \param obj Pointer at the object to iterate.
+ *
+ * A typical example is to use free() to deallocate all the objects in a list.
+ * \code
+ * tommy_list_foreach(&list, (tommy_foreach_func*)free);
+ * \endcode
  */
-typedef void tommy_foreach_func(void* void_a);
+typedef void tommy_foreach_func(void* obj);
 
 /**
  * Foreach function with an argument.
- * The argument is always passed as first parameter.
+ * \param arg Pointer at a generic argument.
+ * \param obj Pointer at the object to iterate.
  */
-typedef void tommy_foreach_arg_func(void* void_arg, void* void_a);
+typedef void tommy_foreach_arg_func(void* arg, void* obj);
 
 /******************************************************************************/
 /* bit hacks */