hash_num.h File Reference

A simple hash with an numerical key implementation. More...

Data Structures
struct	hash_num_entry_s
	This structure represents an entry within a hash table. More...
struct	hash_num_s
	This represents a hash table. More...

Typedefs
typedef struct hash_num_entry_s	HASH_NUM_ENTRY_T
	This structure represents an entry within a hash table.
typedef struct hash_num_s	HASH_NUM_T
	This represents a hash table.

Functions
HASH_NUM_T *	hash_num_new (const unsigned long slots)
	Create a new hash with numerical keys.
HASH_NUM_T *	unsync_hash_num_new (const unsigned long slots)
	Create a new unsynchronized hash with numerical keys.
void	hash_num_clear (HASH_NUM_T *hash, void(*val_free_fn)(void *))
	Clears all keys and values from a hash.
void	hash_num_free (HASH_NUM_T *hash, void(*val_free_fn)(void *))
	Frees memory associated with a hash.
void *	hash_num_add (HASH_NUM_T *hash, unsigned long key, const void *val)
	Add a value to a hash with the given key.
void *	hash_num_del (HASH_NUM_T *hash, unsigned long key)
	Remove a value from the hashmap.
void *	hash_num_get (const HASH_NUM_T *hash, unsigned long key)
	Get a value from the hashmap.
unsigned long *	hash_num_keys (const HASH_NUM_T *hash)
	Obtains all keys currently in the hashmap.
HASH_NUM_T *	hash_num_dup (const HASH_NUM_T *src, void *(*fn)())
	Create a deep copy of a hash hash_num_free should be called on the pointer when no longer needed.
HASH_NUM_T *	hash_num_dup_strval (const HASH_NUM_T *src)
	Create a deep copy of a hash, assuming that the values are NULL-terminated strings.

Detailed Description

A simple hash with an numerical key implementation.

Copyright © 2020 - 2023 DiffusionData Ltd., All Rights Reserved.

Use is subject to licence terms.

NOTICE: All information contained herein is, and remains the property of DiffusionData. The intellectual and technical concepts contained herein are proprietary to DiffusionData and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or copyright law.

Function Documentation

hash_num_add()

void * hash_num_add	(	HASH_NUM_T *	hash,
		unsigned long	key,
		const void *	val
	)

Add a value to a hash with the given key.

If the hash already contains the key, the value is replaced and the old value returned. In this case, the key in the hash is reused; you may need to free() the key that was passed.

Parameters

hash	The hash to which the key/value pair will be added.
key	The key under which to store the value.
val	The value stored under the key.

Return values

void *	If the key already exists in the hash the previous value is returned.
NULL	If the key cannot be found in the hash.

hash_num_clear()

void hash_num_clear	(	HASH_NUM_T *	hash,
		void(*)(void *)	val_free_fn
	)

Clears all keys and values from a hash.

Frees all the keys and values in a HASH_NUM_T, but does not free the hash itself.

Parameters

hash	The hash to be freed.
val_free_fn	A function to be used to free memory associated with the value, or NULL if the values should not be freed.

hash_num_del()

void * hash_num_del	(	HASH_NUM_T *	hash,
		unsigned long	key
	)

Remove a value from the hashmap.

Parameters

hash	The hash from which the key/value pair will be removed.
key	The key for the entry which is to be removed.

Return values

void *	The value which was removed.
NULL	If the key was not found.

hash_num_dup()

HASH_NUM_T * hash_num_dup	(	const HASH_NUM_T *	src,
		void *(*)()	fn
	)

Create a deep copy of a hash hash_num_free should be called on the pointer when no longer needed.

Parameters

src	The hash to copy.
fn	The function used to copy the hash value.

Returns

A copy of the hashmap.

hash_num_dup_strval()

HASH_NUM_T * hash_num_dup_strval

(

const HASH_NUM_T *

src

)

Create a deep copy of a hash, assuming that the values are NULL-terminated strings.

Parameters

src	The hash to copy.

Returns

A copy of the hashmap.

hash_num_free()

void hash_num_free	(	HASH_NUM_T *	hash,
		void(*)(void *)	val_free_fn
	)

Frees memory associated with a hash.

This function can free all memory associated with a hash.

Parameters

hash	The hash to be freed.
val_free_fn	A function to be used to free memory associated with the value, or NULL if the values should not be freed.

hash_num_get()

void * hash_num_get	(	const HASH_NUM_T *	hash,
		unsigned long	key
	)

Get a value from the hashmap.

Parameters

hash	The hash to be searched for the key.
key	The key for which the value is to be returned.

Return values

void *	The value in the hashmap associated with the key, or NULL if not found.
NULL	If the key was not found.

hash_num_keys()

unsigned long * hash_num_keys

(

const HASH_NUM_T *

hash

)

Obtains all keys currently in the hashmap.

Parameters

hash	The hash to be inspected.

Returns

A array of all keys in the hashmap. Call free() on the array when it is no longer required;

hash_num_new()

HASH_NUM_T * hash_num_new

(

const unsigned long

slots

)

Create a new hash with numerical keys.

Parameters

slots

The number of slots available in the hashmap. Keys hash to a slot, and if a slot already contains a key which yields the same hash, it is chained to other entries in the bucket.

Return values

HASH_NUM_T *	Returns a pointer to a HASH_NUM_T structure.
NULL	If the hash cannot be created.

unsync_hash_num_new()

HASH_NUM_T * unsync_hash_num_new

(

const unsigned long

slots

)

Create a new unsynchronized hash with numerical keys.

Parameters

slots

The number of slots available in the hashmap. Keys hash to a slot, and if a slot already contains a key which yields the same hash, it is chained to other entries in the bucket.

Return values

HASH_NUM_T *	Returns a pointer to a HASH_NUM_T structure.
NULL	If the hash cannot be created.