diff --git a/hm.h b/hm.h index d96a455..a8b6f3e 100644 --- a/hm.h +++ b/hm.h @@ -1,5 +1,111 @@ -// hm.h - v1.0.0 - MIT License +// hm.h - v1.0.1 - MIT License // chained hash table implementation as a single header library. +// +// [License and changelog] +// +// See end of file. +// +// [Single header library usage] +// +// Including this header file as such does what you normally expect. +// +// If you also need to include all of the function implementations you +// need to #define HM_IMPLEMENTATION before including the header file +// like this: +// +// #define HM_IMPLEMENTATION +// #include "hm.h" +// +// [Compile-time options] +// +// Note: every compile-time option listed here should be defined before +// the #include "hm.h" or passed to the compiler +// +// #define HM_INITIAL_CAPACITY new_initial_capacity (256) +// +// This macro defines the initial amount of buckets a HashMap will +// have when allocated. +// +// #define HM_MAX_LOAD_FACTOR new_load_factor (0.75f) +// +// This macro defines when a HashMap will be rehashed by surpassing +// the specified load factor for preserving lookup performance. +// +// #define HM_GROWTH_FACTOR new_growth_factor (2) +// +// This macro defines by how much should a HashMap be reallocated when +// rehashing. +// +// #define HM_NO_ASSERT +// +// This macro disables assertions that happen when certain operations +// fail. The disabled assertions will be replaced with a simple +// condition that returns false or NULL when they fail. +// +// #define HM_REALLOC my_realloc (realloc) +// #define HM_FREE my_free (free) +// +// These macros define alternative functions for dynamic allocation +// and deallocation. +// +// [Structure documentation] +// +// HashMap: the main structure used throughout the library +// +// HashMapIterator: a proxy structure used to iterate a HashMap +// +// [Function documentation] +// +// Note: every function that starts with "hm__" is considered a private +// function of this library. +// +// HashMap hm_create(size_t key_size, size_t value_size) +// +// This functions initializes a HashMap structure with the specified key and +// value sizes. If a specified size is 0 then that parameter will be treated +// as a NULL terminated buffer for that HashMap. Allocation of the internal +// buckets is done only at the first hm_put() call. +// +// void hm_free(HashMap *hm) +// +// This functions frees and invalidates all the keys and values stored in the +// specified HashMap. +// +// bool hm_put(HashMap *hm, const void *key, const void *value) +// +// This function inserts a new value associated with the specified key. If the +// key already exists, it's value will be overridden. Return false on error +// only if HM_NO_ASSERT is not defined. +// +// void *hm_get(const HashMap *hm, const void *key) +// +// This function returns the value associated with the specified key. Returns +// NULL if key was not found. +// +// bool hm_remove(HashMap *hm, const void *key) +// +// This function removes the entry associated with the specified key. Returns +// whether the key was found and removed or not. +// +// HashMapIterator hm_iterate(const HashMap *hm) +// +// This function creates a HashMapIterator used to iterate the specfied +// HashMap. +// +// const void *hm_key(const HashMapIterator *it) +// +// This function returns the key of the current entry. Returns NULL if the +// iterator reached the end of the HashMap. +// +// void *hm_value(const HashMapIterator *it) +// +// This function returns the value of the current entry. Returns NULL if the +// iterator reached the end of the HashMap. +// +// void *hm_next(HashMapIterator *it) +// +// This function iterates through the next entry of the HashMap and returns +// it's value. Returns NULL if the iterator reached the end of the HashMap. #ifndef HM_H_ #define HM_H_ @@ -516,6 +622,7 @@ Hm__Bucket *hm__bucket_create(const void *key, size_t key_size, const void *valu /* * Revision history: * + * 1.0.1 (2025-12-30) Added documentation * 1.0.0 (2025-11-18) Initial release */