Implements a lightweight separate-chaining hashtable designed to be flexible enough for embedded systems. More...

#include <stdint.h>

Classes
struct	hashtable_config_t
	Configuration data for a single hashtable instance. More...

struct	hashtable_t
	All data for a single hashtable instance. More...

Macros
#define	HASHTABLE_MIN_ARRAY_COUNT (10u)
	Minimum number of slots in the table array.

#define	HASHTABLE_MIN_BUFFER_SIZE(array_count)
	Helper macro, gets the min. required buffer size for a specific array count. When creating a hashtable with a specific array count, this macro will tell you how much memory is required at a minimum to hold the 'housekeeping' data for that table. Any remaining space is used for key/value pair data storage. More...

Typedefs
typedef size_t	hashtable_size_t
	Defines the type used to represent the size of keys and values stored in the hashtable.

typedef uint32_t(*	hashtable_hashfunc_t) (const char *data, const hashtable_size_t size)

Functions
int	hashtable_create (hashtable_t table, const hashtable_config_t config, void *buffer, size_t buffer_size)

int	hashtable_insert (hashtable_t table, const char key, const hashtable_size_t key_size, const char *value, const hashtable_size_t value_size)

int	hashtable_remove (hashtable_t table, const char key, const hashtable_size_t key_size)

int	hashtable_retrieve (hashtable_t table, const char key, const hashtable_size_t key_size, char *value, hashtable_size_t value_size)

int	hashtable_has_key (hashtable_t table, const char key, const hashtable_size_t key_size)

int	hashtable_bytes_remaining (hashtable_t table, size_t bytes_remaining)

int	hashtable_next_item (hashtable_t table, char key, hashtable_size_t key_size, char *value, hashtable_size_t value_size)

int	hashtable_reset_cursor (hashtable_t *table)

int	hashtable_clear (hashtable_t *table)

int	hashtable_default_config (hashtable_config_t *config, size_t buffer_size)

char *	hashtable_error_message (void)

Detailed Description

Implements a lightweight separate-chaining hashtable designed to be flexible enough for embedded systems.

Author: Erik K. Nyquist

Macro Definition Documentation

◆ HASHTABLE_MIN_BUFFER_SIZE

#define HASHTABLE_MIN_BUFFER_SIZE ( array_count )

Value:

    (sizeof(_keyval_pair_table_data_t) + sizeof(_keyval_pair_list_table_t) +   \
    ((array_count) * sizeof(_keyval_pair_list_t)) +                            \
    sizeof(_keyval_pair_data_block_t))

Helper macro, gets the min. required buffer size for a specific array count. When creating a hashtable with a specific array count, this macro will tell you how much memory is required at a minimum to hold the 'housekeeping' data for that table. Any remaining space is used for key/value pair data storage.

Typedef Documentation

◆ hashtable_hashfunc_t

typedef uint32_t(* hashtable_hashfunc_t) (const char *data, const hashtable_size_t size)

Hash function used for hashing key data

Parameters

data	Pointer to key data
size	Key data size in bytes

Returns: Computed hash value

Function Documentation

◆ hashtable_bytes_remaining()

int hashtable_bytes_remaining	(	hashtable_t *	table,
		size_t *	bytes_remaining
	)

Number of bytes remaining for key/value pair data storage

Parameters

table	Pointer to hashtable instance
bytes_remaining	Pointer to location to store number of bytes remaining

Returns: 0 if successful, -1 if an error occurred. Use hashtable_error_message to get an error message.

◆ hashtable_clear()

int hashtable_clear ( hashtable_t * table )

Clear all stored data from a hashtable instance

Parameters

table Pointer to hashtable instance

Returns: 0 if successful, -1 if an error occurred. Use hashtable_error_message to get an error message.

◆ hashtable_create()

int hashtable_create	(	hashtable_t *	table,
		const hashtable_config_t *	config,
		void *	buffer,
		size_t	buffer_size
	)

Initialize a new hashtable instance

Parameters

table	Pointer to hashtable instance
config	Pointer to hashtable configuration data. May be NULL. If NULL, a default general-purpose configuration will be used.
buffer	Pointer to buffer to use for hashtable data
buffer_size	Size of buffer in bytes

Returns: 0 if successful, 1 if buffer size is not large enough, and -1 if an error occurred. Use hashtable_error_message to get an error message if -1 is returned.

◆ hashtable_default_config()

int hashtable_default_config	(	hashtable_config_t *	config,
		size_t	buffer_size
	)

Populate a configuration structure with the default hash function (FNV-1a), and an array count optimized for the given buffer size.

Parameters

config	Pointer to configuration data structure to populate
buffer_size	Buffer size to generate configuration for

Returns: 0 if successful, -1 if an error occurred. Use hashtable_error_message to get an error message.

◆ hashtable_error_message()

char* hashtable_error_message ( void )

Return a pointer to the last stored error message. When any hashtable function returns -1 to indicate an error, you can call this function to get a pointer to the corresponding error message string. If no error has occurred then this function will return a pointer to an empty string.

Returns: Pointer to error message string

◆ hashtable_has_key()

int hashtable_has_key	(	hashtable_t *	table,
		const char *	key,
		const hashtable_size_t	key_size
	)

Check if a key exists in a table.

Parameters

table	Pointer to hashtable instance
key	Pointer to key data
key_size	Key data size in bytes

Returns: 1 if key exists, 0 if key does not exist, and -1 if an error occurred. Use hashtable_error_message to get an error message.

◆ hashtable_insert()

int hashtable_insert	(	hashtable_t *	table,
		const char *	key,
		const hashtable_size_t	key_size,
		const char *	value,
		const hashtable_size_t	value_size
	)

Insert a new key/value pair into a table. If a key/value pair with the given key already exists, then it will be over-written with the new value.

Parameters

table	Pointer to hashtable instance
key	Pointer to key data
key_size	Key data size in bytes
value	Pointer to value data, may be NULL
value_size	Value data size in bytes, may be 0

Returns: 0 if successful, 1 if there is not enough space left in the buffer for key/value pair data, and -1 if an error occurred. Use hashtable_error_message to get an error message if -1 is returned.

◆ hashtable_next_item()

int hashtable_next_item	(	hashtable_t *	table,
		char **	key,
		hashtable_size_t *	key_size,
		char **	value,
		hashtable_size_t *	value_size
	)

Retrieve pointers to the next key/value pair in the table. This function can be used to iterate over all key/value pairs stored in the table.

Parameters

table	Pointer to hashtable instance
key	Pointer to location to store key pointer
key_size	Pointer to location to store key data size in bytes
value	Pointer to location to store value pointer, may be NULL
value_size	Pointer to location to store value data size in bytes, may be NULL

Returns: 0 if next item was read successfully, 1 if no item was read because all items in the table have been iterated over (in this case you can use hashtable_reset_cursor to reset for another iteration if you need to), and -1 if an error occurred. Use hashtable_error_message to get an error message.

◆ hashtable_remove()

int hashtable_remove	(	hashtable_t *	table,
		const char *	key,
		const hashtable_size_t	key_size
	)

Remove a stored value from a table by key. If the given key does not exist in the table, then the return value will indicate success.

Parameters

table	Pointer to hashtable instance
key	Pointer to key data
key_size	Key data size in bytes

Returns: 0 if successful, 1 if the key does not exist, and -1 if an error occurred. Use hashtable_error_message to get an error message if -1 is returned.

◆ hashtable_reset_cursor()

int hashtable_reset_cursor ( hashtable_t * table )

Reset the key/value pair cursor, which is used for iteration via hashtable_next_item. This allows iterating through a table again after hashtable_next_item has already iterated over the whole table and returned a value of 1.

Parameters

table Pointer to hashtable instance

Returns: 0 if successful, -1 if an error occurred. Use hashtable_error_message to get an error message.

◆ hashtable_retrieve()

int hashtable_retrieve	(	hashtable_t *	table,
		const char *	key,
		const hashtable_size_t	key_size,
		char **	value,
		hashtable_size_t *	value_size
	)

Retrieve a pointer to a value stored in a table by key.

Parameters

table	Pointer to hashtable instance
key	Pointer to key data
key_size	Key data size in bytes
value	Pointer to location to store value pointer, may be NULL
value_size	Pointer to location to store value size, may be NULL

Returns: 0 if successful, 1 if the key does not exist, and -1 if an error occurred. Use hashtable_error_message to get an error message if -1 is returned.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ HASHTABLE_MIN_BUFFER_SIZE

Typedef Documentation

◆ hashtable_hashfunc_t

Function Documentation

◆ hashtable_bytes_remaining()

◆ hashtable_clear()

◆ hashtable_create()

◆ hashtable_default_config()

◆ hashtable_error_message()

◆ hashtable_has_key()

◆ hashtable_insert()

◆ hashtable_next_item()

◆ hashtable_remove()

◆ hashtable_reset_cursor()

◆ hashtable_retrieve()