lib/hashtable.c File Reference

Functions for creating and using a hash table of key-value pairs. More...

#include <stdio.h>
#include <stdlib.h>
#include <assert.h>
#include "uthash.h"
#include "ktx.h"
#include "ktxint.h"

Typedefs
typedef struct _keyAndValue	key_and_value_t
	type of a hash table entry.
Functions
KTX_hash_table	ktxHashTable_Create ()
	Create an empty hash table for storying key-value pairs.
void	ktxHashTable_Destroy (KTX_hash_table This)
	Destroy a hash table.
KTX_error_code	ktxHashTable_AddKVPair (KTX_hash_table This, const char *key, unsigned int valueLen, const void *value)
	Adds a key value pair to a hash table.
KTX_error_code	ktxHashTable_FindValue (KTX_hash_table This, const char *key, unsigned int *pValueLen, void **ppValue)
	Looks up a key a hash table and returns the value.
KTX_error_code	ktxHashTable_Serialize (KTX_hash_table This, unsigned int *pKvdLen, unsigned char **ppKvd)
	Serialize a hash table to a block of data suitable for writing to a file.
KTX_error_code	ktxHashTable_Deserialize (unsigned int kvdLen, void *pKvd, KTX_hash_table *pHt)
	Create a hash table from a block of serialized key-value data read from a file.

---

Detailed Description

Functions for creating and using a hash table of key-value pairs.

Author:

Mark Callow, HI Corporation

Revision:

11914

Date:

2010-07-12 17:46:23 +0900 #

---

Typedef Documentation

key_and_value_t

type of a hash table entry.

---

Function Documentation

KTX_error_code ktxHashTable_AddKVPair	(	KTX_hash_table	This,
		const char *	key,
		unsigned int	valueLen,
		const void *	value
	)

Adds a key value pair to a hash table.

Parameters:

[in]	This	pointer to the target hash table.
[in]	key	pointer to the UTF8 NUL-terminated string to be used as the key.
[in]	valueLen	the number of bytes of data in value.
[in]	value	pointer to the bytes of data constituting the value.

Returns:

KTX_SUCCESS or one of the following error codes.

Exceptions:

KTX_INVALID_VALUE

if This, key or value are NULL, key is an empty string or valueLen == 0.

KTX_hash_table ktxHashTable_Create

(

)

Create an empty hash table for storying key-value pairs.

Returns:

pointer to the newly created hash table or NULL if there is not enough memory.

KTX_error_code ktxHashTable_Deserialize	(	unsigned int	kvdLen,
		void *	pKvd,
		KTX_hash_table *	pHt
	)

Create a hash table from a block of serialized key-value data read from a file.

The caller is responsible for freeing the returned hash table.

Parameters:

[in]	kvdLen	the length of the serialized key-value data.
[in]	pKvd	pointer to the serialized key-value data.
[in,out]	pHt	*pHt is set to point to the created hash table.

Returns:

KTX_SUCCESS or one of the following error codes.

Exceptions:

KTX_INVALID_VALUE	if pKvd or pHt is NULL or kvdLen == 0.
KTX_OUT_OF_MEMORY	there was not enough memory to create the hash table.

void ktxHashTable_Destroy

(

KTX_hash_table

This

)

Destroy a hash table.

All memory associated with the hash table and its keys and values is freed.

Parameters:

[in]

This

pointer to the hash table to be destroyed.

KTX_error_code ktxHashTable_FindValue	(	KTX_hash_table	This,
		const char *	key,
		unsigned int *	pValueLen,
		void **	ppValue
	)

Looks up a key a hash table and returns the value.

Parameters:

[in]	This	pointer to the target hash table.
[in]	key	pointer to a UTF8 NUL-terminated string to find.
[in,out]	pValueLen	*pValueLen is set to the number of bytes of data in the returned value.
[in,out]	ppValue	*ppValue is set to the point to the value for key.

Returns:

KTX_SUCCESS or one of the following error codes.

Exceptions:

KTX_INVALID_VALUE	if This, key or pValueLen or ppValue is NULL.
KTX_NOT_FOUND	an entry matching key was not found.

KTX_error_code ktxHashTable_Serialize	(	KTX_hash_table	This,
		unsigned int *	pKvdLen,
		unsigned char **	ppKvd
	)

Serialize a hash table to a block of data suitable for writing to a file.

The caller is responsible for freeing the data block returned by this function.

Parameters:

[in]	This	pointer to the target hash table.
[in,out]	pKvdLen	*pKvdLen is set to the number of bytes of data in the returned data block.
[in,out]	ppKvd	*ppKvd is set to the point to the block of memory containing the serialized data.

Returns:

KTX_SUCCESS or one of the following error codes.

Exceptions:

KTX_INVALID_VALUE	if This, pKvdLen or ppKvd is NULL.
KTX_OUT_OF_MEMORY	there was not enough memory to serialize the data.