Container Data Structures

Data Structures
struct	_hashtable_config_t
Typedefs
typedef struct _hashtable_config_t	hashtable_config_t
Enumerations
enum	hash_type_t {   HASH_INTPTR,   HASH_STRING,   HASH_STRING_NOCASE,   HASH_CUSTOM }
Functions
bool	drvector_init (drvector_t *vec, uint initial_capacity, bool synch, void(*free_data_func)(void *))
void *	drvector_get_entry (drvector_t *vec, uint idx)
bool	drvector_append (drvector_t *vec, void *data)
bool	drvector_delete (drvector_t *vec)
void	drvector_lock (drvector_t *vec)
void	drvector_unlock (drvector_t *vec)
bool	stri_eq (const char *s1, const char *s2)
void	hashtable_global_config (void *(*alloc_func)(size_t), void(*free_func)(void *, size_t), void(*assert_fail_func)(const char *))
void	hashtable_init (hashtable_t *table, uint num_bits, hash_type_t hashtype, bool str_dup)
void	hashtable_init_ex (hashtable_t *table, uint num_bits, hash_type_t hashtype, bool str_dup, bool synch, void(*free_payload_func)(void *), uint(*hash_key_func)(void *), bool(*cmp_key_func)(void *, void *))
void	hashtable_configure (hashtable_t *table, hashtable_config_t *config)
void *	hashtable_lookup (hashtable_t *table, void *key)
void *	hashtable_lookup_keep_locked (hashtable_t *table, void *key)
bool	hashtable_add (hashtable_t *table, void *key, void *payload)
void *	hashtable_add_replace (hashtable_t *table, void *key, void *payload)
bool	hashtable_remove (hashtable_t *table, void *key)
bool	hashtable_remove_range (hashtable_t *table, void *start, void *end)
void	hashtable_clear (hashtable_t *table)
void	hashtable_delete (hashtable_t *table)
void	hashtable_lock (hashtable_t *table)
void	hashtable_unlock (hashtable_t *table)

---

Typedef Documentation

typedef struct _hashtable_config_t hashtable_config_t

Configuration parameters for a hashtable.

---

Enumeration Type Documentation

enum hash_type_t

The type of hash key

Enumerator:

HASH_INTPTR	A pointer-sized integer or pointer
HASH_STRING	A case-sensitive string
HASH_STRING_NOCASE	A case-insensitive string
HASH_CUSTOM	A custom key. Hash and compare operations must be provided in hashtable_init_ex(). The hash operation can return a full uint, as its result will be truncated via a mod of the hash key bit size. This allows for resizing the table without changing the hash operation.

---

Function Documentation

bool drvector_append	(	drvector_t *	vec,
		void *	data
	)

Adds a new entry to the end of the vector, resizing it if necessary.

bool drvector_delete

(

drvector_t *

vec

)

Destroys all storage for the vector. If free_payload_func was specified calls it for each payload.

void* drvector_get_entry	(	drvector_t *	vec,
		uint	idx
	)

Returns the entry at index idx. For an unsychronized table, the caller is free to directly access the array field of vec.

bool drvector_init	(	drvector_t *	vec,
		uint	initial_capacity,
		bool	synch,
		void(*)(void *)	free_data_func
	)

Initializes a drvector with the given parameters

Parameters:

[out]	vec	The vector to be initialized.
[in]	initial_capacity	The initial number of entries allocated for the vector.
[in]	synch	Whether to synchronize each operation. Even when synch is false, the vector's lock is initialized and can be used via vector_lock() and vector_unlock(), allowing the caller to extend synchronization beyond just the operation in question, to include accessing a looked-up payload, e.g.
[in]	free_data_func	A callback for freeing each data item. Leave it NULL if no callback is needed.

void drvector_lock

(

drvector_t *

vec

)

Acquires the vector lock.

void drvector_unlock

(

drvector_t *

vec

)

Releases the vector lock.

bool hashtable_add	(	hashtable_t *	table,
		void *	key,
		void *	payload
	)

Adds a new entry. Returns false if an entry for key already exists.

Note:

Never use NULL as a payload as that is used for a lookup failure.

void* hashtable_add_replace	(	hashtable_t *	table,
		void *	key,
		void *	payload
	)

Adds a new entry, replacing an existing entry if any.

Note:

Never use NULL as a payload as that is used for a lookup failure.

void hashtable_clear

(

hashtable_t *

table

)

Removes all entries from the table. If free_payload_func was specified calls it for each payload.

void hashtable_configure	(	hashtable_t *	table,
		hashtable_config_t *	config
	)

Configures optional parameters of hashtable operation.

void hashtable_delete

(

hashtable_t *

table

)

Destroys all storage for the table, including all entries and the table itself. If free_payload_func was specified calls it for each payload.

void hashtable_global_config	(	void *(*)(size_t)	alloc_func,
		void(*)(void *, size_t)	free_func,
		void(*)(const char *)	assert_fail_func
	)

The hashtable has parametrized heap and assert routines for flexibility. This routine must be called BEFORE any other hashtable_ routine; else, the defaults will be used.

void hashtable_init	(	hashtable_t *	table,
		uint	num_bits,
		hash_type_t	hashtype,
		bool	str_dup
	)

Initializes a hashtable with the given size, hash type, and whether to duplicate string keys. All operations are synchronized by default.

void hashtable_init_ex	(	hashtable_t *	table,
		uint	num_bits,
		hash_type_t	hashtype,
		bool	str_dup,
		bool	synch,
		void(*)(void *)	free_payload_func,
		uint(*)(void *)	hash_key_func,
		bool(*)(void *, void *)	cmp_key_func
	)

Initializes a hashtable with the given parameters.

Parameters:

[out]	table	The hashtable to be initialized.
[in]	num_bits	The initial number of bits to use for the hash key which determines the initial size of the table itself. The result of the hash function will be truncated to this size. This size will be increased when the table is resized (resizing always doubles the size).
[in]	hashtype	The type of hash to perform.
[in]	str_dup	Whether to duplicate string keys.
[in]	synch	Whether to synchronize each operation. Even when synch is false, the hashtable's lock is initialized and can be used via hashtable_lock() and hashtable_unlock(), allowing the caller to extend synchronization beyond just the operation in question, to include accessing a looked-up payload, e.g.
[in]	free_payload_func	A callback for freeing each payload. Leave it NULL if no callback is needed.
[in]	hash_key_func	A callback for hashing a key. Leave it NULL if no callback is needed and the default is to be used. For HASH_CUSTOM, a callback must be provided. The hash operation can return a full uint, as its result will be truncated via a mod of the hash key bit size. This allows for resizing the table without changing the hash operation.
[in]	cmp_key_func	A callback for comparing two keys. Leave it NULL if no callback is needed and the default is to be used. For HASH_CUSTOM, a callback must be provided.

void hashtable_lock

(

hashtable_t *

table

)

Acquires the hashtable lock.

void* hashtable_lookup	(	hashtable_t *	table,
		void *	key
	)

Returns the payload for the given key, or NULL if the key is not found

void* hashtable_lookup_keep_locked	(	hashtable_t *	table,
		void *	key
	)

Like hashtable_lookup but does not unlock the hashtable lock

bool hashtable_remove	(	hashtable_t *	table,
		void *	key
	)

Removes the entry for key. If free_payload_func was specified calls it for the payload being removed. Returns false if no such entry exists.

bool hashtable_remove_range	(	hashtable_t *	table,
		void *	start,
		void *	end
	)

Removes all entries with key in [start..end). If free_payload_func was specified calls it for each payload being removed. Returns false if no such entry exists.

void hashtable_unlock

(

hashtable_t *

table

)

Releases the hashtable lock.

bool stri_eq	(	const char *	s1,
		const char *	s2
	)

Caseless string compare