Hash table

Classes
struct	clod_table_opts
struct	clod_table_iter
struct	clod_table

Macros
#define	CLOD_TABLE_ITER_INIT   (struct clod_table_iter){ ._internal = 0 }

Functions
struct clod_table *	clod_table_create (const struct clod_table_opts *opts)
void	clod_table_destroy (struct clod_table *t)
size_t	clod_table_len (const struct clod_table *t)
bool	clod_table_add (struct clod_table *t, const void *element, size_t key_size, void **existing_out)
bool	clod_table_set (struct clod_table *t, const void *element, size_t key_size, void **existing_out)
void *	clod_table_get (const struct clod_table *t, const void *key, size_t key_size)
void *	clod_table_del (struct clod_table *t, const void *key, size_t key_size)
bool	clod_table_iter (const struct clod_table *t, struct clod_table_iter *iter)
uint64_t	clod_table_hash_ptr (uint64_t seed, const void *key, size_t key_size, void *user)
int	clod_table_cmp_ptr (const void *key1, size_t key1_size, const void *key2, size_t key2_size, void *user)

Detailed Description

A hash table implementation. It's a pure set at heart, but since methods never return a pointer not supplied by the user, it can be trivially extended to a key->value map by storing the value after the key. The difference in wording between 'element' and 'key' reflects this. If implementing a map, 'element' implies the key and trailing value data associated with it, while 'key' simply implies the key value. If instead a pure set is required - 'element' and 'key' become interchangeable. I would recommend using a struct with the first field being the key and subsequent fields being the value, although for maps with variable-length keys more manual intervention may be required.

Macro Definition Documentation

CLOD_TABLE_ITER_INIT

#define CLOD_TABLE_ITER_INIT   (struct clod_table_iter){ ._internal = 0 }

Definition at line 141 of file table.h.

Function Documentation

clod_table_create()

struct clod_table * clod_table_create

(

const struct clod_table_opts *

opts

)

Create a new table.

Parameters

[in]

opts

Configuration options for the table.

Returns

Initialised table.

Definition at line 190 of file table.c.

clod_table_destroy()

void clod_table_destroy

(

struct clod_table *

t

)

Release resources associated with the table.

Parameters

t	Table to free.

Definition at line 205 of file table.c.

clod_table_len()

size_t clod_table_len

(

const struct clod_table *

t

)

Get the number of elements in the table.

Parameters

[in]

t

Handle to the table.

Returns

Number of elements currently in the table.

Definition at line 209 of file table.c.

clod_table_add()

bool clod_table_add	(	struct clod_table *	t,
		const void *	element,
		size_t	key_size,
		void **	existing_out )

Add an element. If the key already exists the operation fails. A false return and null existing_out indicates an allocation failure.

Parameters

[in]	t	Handle to the table.
[in]	element	Element to insert. The table takes ownership on success.
[in]	key_size	Size of the key.
[out]	existing_out	(nullable) Returns the existing element if the key already existed. The table retains ownership. Returns null on allocation failure.

Returns

True on success. False if the key already existed, or on allocation failure.

Definition at line 212 of file table.c.

clod_table_set()

bool clod_table_set	(	struct clod_table *	t,
		const void *	element,
		size_t	key_size,
		void **	existing_out )

Add or replace an element. If the key already exists, it is replaced. A false return and null existing_out indicates allocation failure.

Parameters

[in]	t	Handle to the table.
[in]	element	Element to insert. The table takes ownership on success.
[in]	key_size	Size of the key.
[out]	existing_out	Returns the existing element if the key already existed. The caller takes ownership on success. Returns null on allocation failure.

Returns

True on success. False on allocation failure.

Definition at line 224 of file table.c.

clod_table_get()

void * clod_table_get	(	const struct clod_table *	t,
		const void *	key,
		size_t	key_size )

Get an element from the table.

Parameters

[in]	t	Handle to the table.
[in]	key	Key to look up. Caller retains ownership.
[in]	key_size	Size of the key.

Returns

Found element or null. The table retains ownership of the element.

Definition at line 236 of file table.c.

clod_table_del()

void * clod_table_del	(	struct clod_table *	t,
		const void *	key,
		size_t	key_size )

Remove an element from the table.

Parameters

[in]	t	Handle to the table.
[in]	key	Key to delete. Caller retains ownership.
[in]	key_size	Size of the key.

Returns

The removed element, or nullptr if the key doesn't exist. The caller takes ownership of the element.

Definition at line 245 of file table.c.

clod_table_iter()

bool clod_table_iter	(	const struct clod_table *	t,
		struct clod_table_iter *	iter )

Get the next element in, or start, an iteration over table elements. Mutating the table, except deleting elements, during iteration can result in existing elements being iterated more than once or not at all.

The iterator should be zero initialised to start an iteration. The iterator is zeroed at the end of the iteration.

Parameters

[in]	t	Handle to the table.
[in,out]	iter	Iterator to be incremented.

Returns

If the next element was found.

Definition at line 258 of file table.c.

clod_table_hash_ptr()

uint64_t clod_table_hash_ptr	(	uint64_t	seed,
		const void *	key,
		size_t	key_size,
		void *	user )

A hash method that hashes the pointer value itself instead of the data it references. Provided here as a helper for using the table as a pointer set.

Definition at line 172 of file table.c.

clod_table_cmp_ptr()

int clod_table_cmp_ptr	(	const void *	key1,
		size_t	key1_size,
		const void *	key2,
		size_t	key2_size,
		void *	user )

A comparison method that compares the pointer values themselves instead of the data they reference. Provided here as a helper for using the table as a pointer set.

Definition at line 177 of file table.c.