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.

void	ktxHashList_ConstructCopy (ktxHashList *pHead, ktxHashList orig)
	Construct a hash list by copying another.

void	ktxHashList_Destruct (ktxHashList *pHead)
	Destruct a hash list.

KTX_error_code	ktxHashList_Create (ktxHashList **ppHl)
	Create an empty hash list for storing key-value pairs.

KTX_error_code	ktxHashList_CreateCopy (ktxHashList **ppHl, ktxHashList orig)
	Create a copy of a hash list.

void	ktxHashList_Destroy (ktxHashList *pHead)
	Destroy a hash list.

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.

KTX_error_code	ktxHashList_DeleteKVPair (ktxHashList pHead, const char key)
	Delete a key value pair in a hash list.

KTX_error_code	ktxHashList_DeleteEntry (ktxHashList pHead, ktxHashListEntry pEntry)
	Delete an entry from a hash list.

KTX_error_code	ktxHashList_FindEntry (ktxHashList pHead, const char key, ktxHashListEntry **ppEntry)
	Looks up a key in a hash list and returns the entry.

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.

ktxHashListEntry *	ktxHashList_Next (ktxHashListEntry *entry)
	Returns the next entry in a ktxHashList.

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.

KTX_error_code	ktxHashList_Sort (ktxHashList *pHead)
	Sort a hash list in order of the UTF8 codepoints.

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.

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.

The value can be empty, i.e, its length can be 0.

Parameters

[in]	pHead	pointer to the head of the target hash list.
[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 pHead, 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] pHead pointer to the location to write the list head.

◆ ktxHashList_ConstructCopy()

void ktxHashList_ConstructCopy	(	ktxHashList *	pHead,
		ktxHashList	orig
	)

Construct a hash list by copying another.

Parameters

[in]	pHead	pointer to head of the list.
[in]	orig	head of the original hash list.

◆ ktxHashList_Create()

KTX_error_code ktxHashList_Create ( ktxHashList ** ppHl )

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

Parameters

[in,out] ppHl address 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_MEMORY if not enough memory.

◆ ktxHashList_CreateCopy()

KTX_error_code ktxHashList_CreateCopy	(	ktxHashList **	ppHl,
		ktxHashList	orig
	)

Create a copy of a hash list.

Parameters

[in,out]	ppHl	address of a variable in which to set a pointer to the newly created hash list.
[in]	orig	head of the ktxHashList to copy.

Returns: KTX_SUCCESS or one of the following error codes.

Exceptions

KTX_OUT_OF_MEMORY if not enough memory.

◆ ktxHashList_DeleteEntry()

KTX_error_code ktxHashList_DeleteEntry	(	ktxHashList *	pHead,
		ktxHashListEntry *	pEntry
	)

Delete an entry from a hash list.

Parameters

[in]	pHead	pointer to the head of the target hash list.
[in]	pEntry	pointer to the ktxHashListEntry to delete.

Returns: KTX_SUCCESS or one of the following error codes.

Exceptions

KTX_INVALID_VALUE if pHead is NULL or key is an empty string.

◆ ktxHashList_DeleteKVPair()

KTX_error_code ktxHashList_DeleteKVPair	(	ktxHashList *	pHead,
		const char *	key
	)

Delete a key value pair in a hash list.

Is a nop if the key is not in the hash.

Parameters

[in]	pHead	pointer to the head of the target hash list.
[in]	key	pointer to the UTF8 NUL-terminated string to be used as the key.

Returns: KTX_SUCCESS or one of the following error codes.

Exceptions

KTX_INVALID_VALUE if pHead is NULL or key is an empty string.

◆ 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.

Note: The bytes of the 32-bit key-value lengths within the serialized data are expected to be in native endianness.

Parameters

[in]	pHead	pointer to the head of the target hash list.
[in]	kvdLen	the length of the serialized key-value data.
[in]	pKvd	pointer to the serialized key-value data. table.

Returns: KTX_SUCCESS or one of the following error codes.

Exceptions

KTX_INVALID_OPERATION	if `pHead` does not point to an empty list.
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.

◆ 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] pHead pointer 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] pHead pointer to the hash list to be destroyed.

◆ ktxHashList_FindEntry()

KTX_error_code ktxHashList_FindEntry	(	ktxHashList *	pHead,
		const char *	key,
		ktxHashListEntry **	ppEntry
	)

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

Parameters

[in]	pHead	pointer to the head of the target hash list.
[in]	key	pointer to a UTF8 NUL-terminated string to find.
[in,out]	ppEntry	`*ppEntry` is set to the point at the ktxHashListEntry.

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.

◆ 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]	pHead	pointer to the head of the target hash list.
[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.

◆ ktxHashList_Next()

ktxHashListEntry * ktxHashList_Next ( ktxHashListEntry * entry )

Returns the next entry in a ktxHashList.

Use for iterating through the list:

ktxHashListEntry* entry;
for (entry = listHead; entry != NULL; entry = ktxHashList_Next(entry)) {
   ...
};

Note

Parameters

[in] entry pointer to a hash list entry. Note that a ktxHashList*, i.e. the list head, is also a pointer to an entry so can be passed to this function.

Returns: a pointer to the next entry or NULL.

◆ 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]	pHead	pointer 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 or NULL. if the hash list is empty.

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.

◆ ktxHashList_Sort()

KTX_error_code ktxHashList_Sort ( ktxHashList * pHead )

Sort a hash list in order of the UTF8 codepoints.

Parameters

[in] pHead pointer to the head of the target hash list.

Returns: KTX_SUCCESS or one of the following error codes.

Exceptions

KTX_INVALID_VALUE if This is NULL.

Public Member Functions

Detailed Description

Member Function Documentation

◆ ktxHashList_AddKVPair()

◆ ktxHashList_Construct()

◆ ktxHashList_ConstructCopy()

◆ ktxHashList_Create()

◆ ktxHashList_CreateCopy()

◆ ktxHashList_DeleteEntry()

◆ ktxHashList_DeleteKVPair()

◆ ktxHashList_Deserialize()

◆ ktxHashList_Destroy()

◆ ktxHashList_Destruct()

◆ ktxHashList_FindEntry()

◆ ktxHashList_FindValue()

◆ ktxHashList_Next()

◆ ktxHashList_Serialize()

◆ ktxHashList_Sort()