A container using HashBuckets to allow for fast lookup of key-value pairs. More...

#include <hash_table.h>

Collaboration diagram for HashTable:

Public Member Functions
HashTable *	AllocateHashTable (const uint32 initial_size, const uint8 load_percentage, uint32(hash_fn)(const void const key_p), HashBucket (create_buckets_fn)(const uint32 num_buckets), void(free_bucket_fn)(HashBucket const bucket_p), bool(fill_bucket_fn)(HashBucket const bucket_p, const void const key_p, const void const value_p), bool(compare_keys_fn)(const void const bucket_key_p, const void const key_p), void(print_bucket_fn)(const HashBucket const bucket_p, OutputStream const stream_p), bool(save_bucket_fn)(const HashBucket const bucket_p, FILE *out_f))
	Allocate a new HashTable. More...

void	FreeHashTable (HashTable *const hash_table_p)
	Free a HashTable. More...

void	ClearHashTable (HashTable *const hash_table_p)
	Clear a HashTable. More...

bool	IsValidHashBucket (const HashBucket *const bucket_p)
	Does the HashBucket contain a valid key-value pair. More...

bool	PutInHashTable (HashTable const hash_table_p, const void const key_p, const void *const value_p)
	Put a key-value pair in the HashTable. More...

const void *	GetFromHashTable (const HashTable const hash_table_p, const void const key_p)
	For a given key, get the value from a HashTable. More...

void **	GetKeysIndexFromHashTable (const HashTable *const hash_table_p)
	Get a new array with pointers to each of the keys in a given HashTable. More...

void	FreeKeysIndex (void **index_pp)
	Free an index array previously returned by a call to GetKeysIndexFromHashTable. More...

void	RemoveFromHashTable (HashTable const hash_table_p, const void const key_p)
	For a given key, empty the corresponding bucket in a HashTable. More...

void	PrintHashTable (const HashTable const hash_table_p, OutputStream const stream_p)
	Print out a HashTable to a given stream. More...

HashTable *	CopyHashTable (const HashTable *const src_table_p, const bool deep_copy_if_necessary)
	Copy a HashTable. More...

bool	SaveHashTable (const HashTable const table_p, const char const filename_s, int(compare_fn)(const void v0_p, const void *v1_p))
	Save a HashTable to a file. More...

bool	LoadHashTable (HashTable const table_p, char current_path_s, const char *const filename_s)
	Load the contents of a previously-saved HashTable file into a HashTable. More...

uint32	GetHashTableSize (const HashTable *const table_p)
	Get the number of entries in a HashTable. More...

Data Fields
uint32	ht_size
	The number of valid HashBuckets in the HashTable. More...

uint32	ht_capacity
	The actual number of HashBucket slots in the HashTable. More...

uint8	ht_load
	How full to let the hash table get before rehashing, between 0 and 100. More...

uint32	ht_load_limit
	The ht_capacity * ht_load. More...

HashBucket *	ht_buckets_p
	The HashBuckets. More...

uint32(*	ht_hash_fn )(const void *)
	Function for calculating the hashed value of a HashBucket key. More...

HashBucket (	ht_create_buckets_fn )(const uint32 num_buckets)
	Function for creating the HashBuckets. More...

void(*	ht_free_bucket_fn )(HashBucket *const bucket_p)
	Function for feeing a HashBucket. More...

bool(*	ht_fill_bucket_fn )(HashBucket const bucket_p, const void const key_p, const void *const value_p)
	Function for filling a HashBucket. More...

bool(*	ht_compare_keys_fn )(const void const bucket_key_p, const void const key_p)
	Function for comparing the keys of two HashBuckets. More...

void(*	ht_print_bucket_fn )(const HashBucket const bucket_p, OutputStream const stream_p)
	Function for printing out the HashBuckets in this HashTable. More...

bool(*	ht_save_bucket_fn )(const HashBucket const bucket_p, FILE out_f)
	Function for saving the HashBuckets in this HashTable to a file. More...

Detailed Description

A container using HashBuckets to allow for fast lookup of key-value pairs.

Member Function Documentation

◆ AllocateHashTable()

HashTable * AllocateHashTable	(	const uint32	initial_size,
		const uint8	load_percentage,
		uint32()(const void const key_p)	hash_fn,
		HashBucket ()(const uint32 num_buckets)	create_buckets_fn,
		void()(HashBucket const bucket_p)	free_bucket_fn,
		bool()(HashBucket const bucket_p, const void const key_p, const void const value_p)	fill_bucket_fn,
		bool()(const void const bucket_key_p, const void *const key_p)	compare_keys_fn,
		void()(const HashBucket const bucket_p, OutputStream *const stream_p)	print_bucket_fn,
		bool()(const HashBucket const bucket_p, FILE *out_f)	save_bucket_fn
	)

Allocate a new HashTable.

Parameters

initial_size	The initial number of HashBuckets for this HashTable.
load_percentage	The percentage value for how full the HashTable should be allowed to become before it is extended.
hash_fn	The callback function to use for generating the hashed_key value for each HashBucket in the HashTable from its key.
create_buckets_fn	The callback function used to create the given number of HashBuckets.
free_bucket_fn	The callback function used to free each given HashBucket when the HashTable is freed.
fill_bucket_fn	The callback function to use when adding a key-value pair to the HashTable.
compare_keys_fn	The callback function that takes 2 HashBuckets and determines whether they have the same key.
print_bucket_fn	The callback function that prints out the contents of the given HashBucket to the given stream.
save_bucket_fn	The callback function to use for saving each HashBucket when saving the HashTable to a file.

Returns: The new HashTable or NULL if there was an error.

◆ FreeHashTable()

void FreeHashTable ( HashTable *const hash_table_p )

Free a HashTable.

Parameters

hash_table_p The HashTable to free.

◆ ClearHashTable()

void ClearHashTable ( HashTable *const hash_table_p )

Clear a HashTable.

Parameters

hash_table_p The HashTable to clear.

◆ IsValidHashBucket()

bool IsValidHashBucket ( const HashBucket *const bucket_p )

Does the HashBucket contain a valid key-value pair.

Parameters

bucket_p The HashBucket.

Returns: TRUE if the bucket does contain a valid key-value pair, FALSE if it is empty.

◆ PutInHashTable()

bool PutInHashTable	(	HashTable *const	hash_table_p,
		const void *const	key_p,
		const void *const	value_p
	)

Put a key-value pair in the HashTable.

If a bucket already contains this key, its value will be overwritten. If the HashTable is getting beyond its designated load, its capacity will be extended.

Parameters

hash_table_p	The HashTable to put for the key-value pair in.
key_p	The key.
value_p	The value.

Returns: true if the key-value pair were added successfully, false otherwise.

◆ GetFromHashTable()

const void * GetFromHashTable	(	const HashTable *const	hash_table_p,
		const void *const	key_p
	)

For a given key, get the value from a HashTable.

If the key is not in the HashTable, this will return NULL

Parameters

hash_table_p	The HashTable to search for the value in.
key_p	The key.

Returns: The value or NULL if there is not a matching value for the given key.

◆ GetKeysIndexFromHashTable()

void ** GetKeysIndexFromHashTable ( const HashTable *const hash_table_p )

Get a new array with pointers to each of the keys in a given HashTable.

Parameters

hash_table_p The HashTable to get the keys from.

See also: FreeKeysIndex

◆ FreeKeysIndex()

void FreeKeysIndex ( void ** index_pp )

Free an index array previously returned by a call to GetKeysIndexFromHashTable.

Parameters

index_pp The array of index pointers to free.

◆ RemoveFromHashTable()

void RemoveFromHashTable	(	HashTable *const	hash_table_p,
		const void *const	key_p
	)

For a given key, empty the corresponding bucket in a HashTable.

If the key is not in the HashTable, this will do nothing

Parameters

hash_table_p	The HashTable to search for the in.
key_p	The key.

◆ PrintHashTable()

void PrintHashTable	(	const HashTable *const	hash_table_p,
		OutputStream *const	stream_p
	)

Print out a HashTable to a given stream.

Parameters

hash_table_p	The HashTable to print out.
stream_p	The OutputStream to print the HashTable to.

◆ CopyHashTable()

HashTable * CopyHashTable	(	const HashTable *const	src_table_p,
		const bool	deep_copy_if_necessary
	)

Copy a HashTable.

Parameters

src_table_p	The HashTable to copy.
deep_copy_if_necessary	How to avoid potential memory corruption. Check the source table's memory settings.

MF_DEEP_COPY: our copied table will work correctly MF_SHADOW_USE: our copied table will work correctly MF_SHALLOW_COPY: This will cause memory corruption since both the cource and destination tables will try to free the same memory. So switch to either MF_DEEP_COPY or MF_SHADOW_USE depending upon deep_copy_if_necessary.

Returns: The copied HashTable or NULL upon error.

◆ SaveHashTable()

bool SaveHashTable	(	const HashTable *const	table_p,
		const char *const	filename_s,
		int()(const void v0_p, const void *v1_p)	compare_fn
	)

Save a HashTable to a file.

Parameters

table_p	The HashTable to save.
filename_s	The filename where the HashTable will be saved to.
compare_fn	An optional callback function allowing the contents of the HashTable to be saved in a user-defined order. If this is `NULL` then the contents will be saved in an undetermined order.

Returns: true if the data was saved successfully, false otherwise.

◆ LoadHashTable()

bool LoadHashTable	(	HashTable *const	table_p,
		char *	current_path_s,
		const char *const	filename_s
	)

Load the contents of a previously-saved HashTable file into a HashTable.

Parameters

table_p	The HastTable to load the data into.
current_path_s	The directory containing the saved file.
filename_s	The filename to load.

Returns: true if the data was loaded successfully, false otherwise.

◆ GetHashTableSize()

uint32 GetHashTableSize ( const HashTable *const table_p )

Get the number of entries in a HashTable.

Parameters

table_p The HashTable to get the size of.

Returns: The number of entries in the HashTable.

Field Documentation

◆ ht_size

uint32 ht_size

The number of valid HashBuckets in the HashTable.

◆ ht_capacity

uint32 ht_capacity

The actual number of HashBucket slots in the HashTable.

◆ ht_load

uint8 ht_load

How full to let the hash table get before rehashing, between 0 and 100.

◆ ht_load_limit

uint32 ht_load_limit

The ht_capacity * ht_load.

◆ ht_buckets_p

HashBucket* ht_buckets_p

The HashBuckets.

◆ ht_hash_fn

uint32(* ht_hash_fn) (const void *)

Function for calculating the hashed value of a HashBucket key.

◆ ht_create_buckets_fn

HashBucket*(* ht_create_buckets_fn) (const uint32 num_buckets)

Function for creating the HashBuckets.

◆ ht_free_bucket_fn

void(* ht_free_bucket_fn) (HashBucket *const bucket_p)

Function for feeing a HashBucket.

◆ ht_fill_bucket_fn

bool(* ht_fill_bucket_fn) (HashBucket *const bucket_p, const void *const key_p, const void *const value_p)

Function for filling a HashBucket.

◆ ht_compare_keys_fn

bool(* ht_compare_keys_fn) (const void *const bucket_key_p, const void *const key_p)

Function for comparing the keys of two HashBuckets.

◆ ht_print_bucket_fn

void(* ht_print_bucket_fn) (const HashBucket *const bucket_p, OutputStream *const stream_p)

Function for printing out the HashBuckets in this HashTable.

◆ ht_save_bucket_fn

bool(* ht_save_bucket_fn) (const HashBucket *const bucket_p, FILE *out_f)

Function for saving the HashBuckets in this HashTable to a file.

The documentation for this struct was generated from the following file:

hash_table.h

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

◆ AllocateHashTable()

◆ FreeHashTable()

◆ ClearHashTable()

◆ IsValidHashBucket()

◆ PutInHashTable()

◆ GetFromHashTable()

◆ GetKeysIndexFromHashTable()

◆ FreeKeysIndex()

◆ RemoveFromHashTable()

◆ PrintHashTable()

◆ CopyHashTable()

◆ SaveHashTable()

◆ LoadHashTable()

◆ GetHashTableSize()

Field Documentation

◆ ht_size

◆ ht_capacity

◆ ht_load

◆ ht_load_limit

◆ ht_buckets_p

◆ ht_hash_fn

◆ ht_create_buckets_fn

◆ ht_free_bucket_fn

◆ ht_fill_bucket_fn

◆ ht_compare_keys_fn

◆ ht_print_bucket_fn

◆ ht_save_bucket_fn