libktx - The KTX Library
ktxHashList Class Reference

Opaque handle to a ktxHashList. More...

#include <ktx.h>

Public Member Functions

void ktxHashList_Construct (ktxHashList *pHead)
 Construct an empty hash list for storing key-value pairs. More...
 
void ktxHashList_Destruct (ktxHashList *pHead)
 Destruct a hash list. More...
 
KTX_error_code ktxHashList_Create (ktxHashList **ppHl)
 Create an empty hash list for storing key-value pairs. More...
 
void ktxHashList_Destroy (ktxHashList *pHead)
 Destroy a hash list. More...
 
KTX_error_code ktxHashList_AddKVPair (ktxHashList *pHead, const char *key, unsigned int valueLen, const void *value)
 Add a key value pair to a hash list. More...
 
KTX_error_code ktxHashList_FindValue (ktxHashList *pHead, const char *key, unsigned int *pValueLen, void **ppValue)
 Looks up a key in a hash list and returns the value. More...
 
KTX_error_code ktxHashList_Serialize (ktxHashList *pHead, unsigned int *pKvdLen, unsigned char **ppKvd)
 Serialize a hash list to a block of data suitable for writing to a file. More...
 
KTX_error_code ktxHashList_Deserialize (ktxHashList *pHead, unsigned int kvdLen, void *pKvd)
 Construct a hash list from a block of serialized key-value data read from a file. More...
 

Detailed Description

Opaque handle to a ktxHashList.

Member Function Documentation

◆ ktxHashList_AddKVPair()

KTX_error_code ktxHashList_AddKVPair ( ktxHashList pHead,
const char *  key,
unsigned int  valueLen,
const void *  value 
)

Add a key value pair to a hash list.

Parameters
[in]pHeadpointer to the head of the target hash list.
[in]keypointer to the UTF8 NUL-terminated string to be used as the key.
[in]valueLenthe number of bytes of data in value.
[in]valuepointer to the bytes of data constituting the value.
Returns
KTX_SUCCESS or one of the following error codes.
Exceptions
KTX_INVALID_VALUEif This, key or value are NULL, key is an empty string or valueLen == 0.

◆ ktxHashList_Construct()

void ktxHashList_Construct ( ktxHashList pHead)

Construct an empty hash list for storing key-value pairs.

Parameters
[in]pHeadpointer to the location to write the list head.

◆ ktxHashList_Create()

KTX_error_code ktxHashList_Create ( ktxHashList **  ppHl)

Create an empty hash list for storing key-value pairs.

Parameters
[in,out]ppHladdress of a variable in which to set a pointer to the newly created hash list.
Returns
KTX_SUCCESS or one of the following error codes.
Exceptions
KTX_OUT_OF_MEMORYif not enough memory.

◆ ktxHashList_Deserialize()

KTX_error_code ktxHashList_Deserialize ( ktxHashList pHead,
unsigned int  kvdLen,
void *  pKvd 
)

Construct a hash list from a block of serialized key-value data read from a file.

Parameters
[in]pHeadpointer to the head of the target hash list.
[in]kvdLenthe length of the serialized key-value data.
[in]pKvdpointer to the serialized key-value data. table.
Returns
KTX_SUCCESS or one of the following error codes.
Exceptions
KTX_INVALID_OPERATIONif pHead does not point to an empty list.
KTX_INVALID_VALUEif pKvd or pHt is NULL or kvdLen == 0.
KTX_OUT_OF_MEMORYthere was not enough memory to create the hash table.

◆ ktxHashList_Destroy()

void ktxHashList_Destroy ( ktxHashList pHead)

Destroy a hash list.

All memory associated with the hash list's keys and values is freed. The hash list is also freed.

Parameters
[in]pHeadpointer to the hash list to be destroyed.

◆ ktxHashList_Destruct()

void ktxHashList_Destruct ( ktxHashList pHead)

Destruct a hash list.

All memory associated with the hash list's keys and values is freed.

Parameters
[in]pHeadpointer to the hash list to be destroyed.

◆ ktxHashList_FindValue()

KTX_error_code ktxHashList_FindValue ( ktxHashList pHead,
const char *  key,
unsigned int *  pValueLen,
void **  ppValue 
)

Looks up a key in a hash list and returns the value.

Parameters
[in]pHeadpointer to the head of the target hash list.
[in]keypointer 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_VALUEif This, key or pValueLen or ppValue is NULL.
KTX_NOT_FOUNDan entry matching key was not found.

◆ ktxHashList_Serialize()

KTX_error_code ktxHashList_Serialize ( ktxHashList pHead,
unsigned int *  pKvdLen,
unsigned char **  ppKvd 
)

Serialize a hash list 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]pHeadpointer to the head of the target hash list.
[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_VALUEif This, pKvdLen or ppKvd is NULL.
KTX_OUT_OF_MEMORYthere was not enough memory to serialize the data.