Hash Map

UCX provides a basic hash map implementation with a configurable amount of buckets. If you do not specify the number of buckets, a default of 16 buckets will be used.

You can always rehash the map with cxMapRehash() to change the number of buckets to something more efficient, but you need to be careful, because when you use this function you are effectively locking into using this specific hash map implementation, and you would need to remove all calls to this function when you want to exchange the concrete map implementation with something different.

#include <cx/hash_map.h>

CxMap *cxHashMapCreate(const CxAllocator *allocator,
        size_t itemsize, size_t buckets);

CxMap *cxHashMapCreateSimple(size_t itemsize);

int cxMapRehash(CxMap *map);

The function cxHashMapCreate() creates a new map where both the map structure and the contained buckets are allocated by the specified allocator. The default stdlib allocator is used in cxHashMapCreateSimple().

The map will store items of size itemsize. You can use the CX_STORE_POINTERS macro for itemsize to indicate that the map shall store pointers instead of actual items.

If you pass zero for the number of buckets, or use cxHashMapSimple(), the map is initialized with a default of 16 buckets, otherwise the specified number of buckets is allocated.

The function cxMapRehash() allocates a new array of buckets and re-distributes all elements, if the number of elements exceeds ¾ of the number of buckets. Otherwise, no action is performed and this function simply returns 0. After rehashing, the number of buckets is at least 2½ times the number of elements.

Last modified: 06 April 2025