Hashmap API

String-keyed hash map with separate chaining. More...

Functions
bool	hashmap_init (t_hashmap *map, size_t initial_cap, void(*del)(void *))
	Initializes an empty hash map.
void	hashmap_free (t_hashmap *map)
	Frees a hash map and all of its contents.
void	hashmap_clear (t_hashmap *map)
	Removes all key/value pairs from a hash map.
bool	hashmap_put (t_hashmap *map, const char *key, void *value)
	Inserts a key/value pair, replacing any existing value for the key.
const void *	hashmap_get_const (const t_hashmap *map, const char *key)
	Retrieves the value associated with a key.
const t_key_value **	hashmap_get_all (const t_hashmap *map)
	Collects every key/value pair stored in the map.
bool	hashmap_remove (t_hashmap *map, const char *key)
	Removes the pair associated with a key.
bool	hashmap_contains (const t_hashmap *map, const char *key)
	Tests whether a key is present in the map.
t_key_value *	key_value_new (const char *key, void *value)
	Allocates a key/value pair.
void	key_value_free (t_key_value **pair, void(*del)(void *))
	Frees a key/value pair and its contents.

Detailed Description

String-keyed hash map with separate chaining.

Functions to create, populate, query and destroy a hash map that maps NUL-terminated string keys to arbitrary value pointers.

Function Documentation

hashmap_clear()

void hashmap_clear

(

t_hashmap *

map

)

Removes all key/value pairs from a hash map.

Frees every stored pair, resets the map size to 0 and empties the bucket chains, while keeping the bucket array, hash function and value destructor available for later insertions.

Warning

map must be initialized before calling this function.

Parameters

map	Pointer to the map to clear (borrowed).

Here is the call graph for this function:

hashmap_contains()

bool hashmap_contains	(	const t_hashmap *	map,
		const char *	key
	)

Tests whether a key is present in the map.

Warning

map must be initialized before calling this function.

Parameters

map	Pointer to an initialized map (borrowed, read-only).
key	NUL-terminated key to look for (borrowed, read-only).

Returns

true if the key is present, false otherwise.

Here is the call graph for this function:

Here is the caller graph for this function:

hashmap_free()

void hashmap_free

(

t_hashmap *

map

)

Frees a hash map and all of its contents.

Releases every stored pair: each key copy is freed, each value is passed to the map's del callback (if any), and the bucket array is freed. The map is reset to a zeroed state afterwards.

Parameters

map	Pointer to the map to free (borrowed).

Here is the call graph for this function:

hashmap_get_all()

const t_key_value ** hashmap_get_all

(

const t_hashmap *

map

)

Collects every key/value pair stored in the map.

Builds a freshly allocated, NULL-terminated array holding a pointer to each of the map's pairs, in unspecified bucket order.

Note

The returned array is owned by the caller and must be freed with a single free(). The pairs it points to are borrowed, read-only and remain owned by the map; do not free them and do not use the array after the map (or any referenced pair) has been modified or freed.

Parameters

map	Pointer to an initialized map (borrowed, read-only).

Returns

NULL-terminated array of pair pointers (owned by caller), or NULL on memory allocation failure. The array contains only the NULL terminator when the map holds no pairs.

hashmap_get_const()

const void * hashmap_get_const	(	const t_hashmap *	map,
		const char *	key
	)

Retrieves the value associated with a key.

Note

The returned pointer is borrowed from map and exposed as read-only. It becomes invalid if the matching pair is removed or replaced, or if map is freed.

Parameters

map	Pointer to an initialized map (borrowed, read-only).
key	NUL-terminated key to look up (borrowed, read-only).

Returns

Associated value (borrowed, read-only), or NULL if the key is not present.

Here is the call graph for this function:

Here is the caller graph for this function:

hashmap_init()

bool hashmap_init	(	t_hashmap *	map,
		size_t	initial_cap,
		void(*)(void *)	del
	)

Initializes an empty hash map.

Allocates an initial bucket array of initial_cap slots and installs hash_string as the default hash function. The del callback is stored as-is and used later to release stored values; the map does not own del itself.

Note

When initial_cap is 0, the map starts with no buckets and grows to HASHMAP_INIT_CAP on the first insertion that requires storage; this case does not allocate and cannot fail because of initial_cap.

On failure, map is left in a zeroed state.

Parameters

map	Pointer to the map structure to initialize (borrowed, initialized by the function).
initial_cap	Initial capacity of the bucket array.
del	Optional destructor applied to each stored value on removal or free.

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

hashmap_put()

bool hashmap_put	(	t_hashmap *	map,
		const char *	key,
		void *	value
	)

Inserts a key/value pair, replacing any existing value for the key.

The key is duplicated internally, so the caller keeps ownership of the key buffer. If the key already exists, its previous value is released through the map's del callback before the new value takes its place. The bucket array grows automatically when needed.

Note

On success, ownership of value is transferred to the map and is released through the del callback on removal or on hashmap_free().

On failure, ownership of value remains with the caller.

If key already exists and value is the same pointer as the currently stored value, hashmap_put() is a no-op and returns true.

Warning

map must be initialized before calling this function.

When the map destructor is not NULL, each stored value pointer must have unique ownership. Storing the same owned pointer under several different keys can cause a double free on removal or hashmap_free().

Parameters

map	Pointer to an initialized map (borrowed).
key	NUL-terminated key to duplicate internally (borrowed, read-only).
value	Value to associate with key (ownership taken by map on success).

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

hashmap_remove()

bool hashmap_remove	(	t_hashmap *	map,
		const char *	key
	)

Removes the pair associated with a key.

The matching pair is unlinked and freed: its key copy is freed and its value is passed to the map's del callback (if any).

Warning

map must be initialized before calling this function.

Parameters

map	Pointer to an initialized map (borrowed).
key	NUL-terminated key to remove (borrowed, read-only).

Returns

true if a pair was removed, false if the key was not found.

Here is the call graph for this function:

key_value_free()

void key_value_free	(	t_key_value **	pair,
		void(*)(void *)	del
	)

Frees a key/value pair and its contents.

Frees the duplicated key, passes the value to del (if provided) and frees the pair itself. The caller's pointer is set to NULL. Safe to call with a NULL pair pointer or a NULL pair.

Parameters

pair	Address of the pair pointer to free (set to NULL on return).
del	Optional destructor applied to the stored value (may be NULL).

Here is the caller graph for this function:

key_value_new()

t_key_value * key_value_new	(	const char *	key,
		void *	value
	)

Allocates a key/value pair.

Duplicates key into a private buffer and stores value by reference. The caller therefore keeps ownership of the key buffer, while the new pair takes ownership of value.

Note

On success, ownership of value is transferred to the pair. On failure, value is not retained and the caller keeps its ownership.

Parameters

key	NUL-terminated key to copy (borrowed; duplicated internally).
value	Value to store (ownership transferred on success).

Returns

Pointer to the new pair (owned by caller), or NULL on allocation failure.

Here is the call graph for this function:

Here is the caller graph for this function: