.TH "ktxHashList" 3 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "libktx Reference" \" -*- nroff -*-
.ad l
.nh
.SH NAME
ktxHashList \- Opaque handle to a \fBktxHashList\fP\&.  

.SH SYNOPSIS
.br
.PP
.PP
\fR#include <ktx\&.h>\fP
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "void \fBktxHashList_Construct\fP (\fBktxHashList\fP *pHead)"
.br
.RI "Construct an empty hash list for storing key-value pairs\&. "
.ti -1c
.RI "void \fBktxHashList_ConstructCopy\fP (\fBktxHashList\fP *pHead, \fBktxHashList\fP orig)"
.br
.RI "Construct a hash list by copying another\&. "
.ti -1c
.RI "void \fBktxHashList_Destruct\fP (\fBktxHashList\fP *pHead)"
.br
.RI "Destruct a hash list\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxHashList_Create\fP (\fBktxHashList\fP **ppHl)"
.br
.RI "Create an empty hash list for storing key-value pairs\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxHashList_CreateCopy\fP (\fBktxHashList\fP **ppHl, \fBktxHashList\fP orig)"
.br
.RI "Create a copy of a hash list\&. "
.ti -1c
.RI "void \fBktxHashList_Destroy\fP (\fBktxHashList\fP *pHead)"
.br
.RI "Destroy a hash list\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxHashList_AddKVPair\fP (\fBktxHashList\fP *pHead, const char *key, unsigned int valueLen, const void *value)"
.br
.RI "Add a key value pair to a hash list\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxHashList_DeleteKVPair\fP (\fBktxHashList\fP *pHead, const char *key)"
.br
.RI "Delete a key value pair in a hash list\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxHashList_DeleteEntry\fP (\fBktxHashList\fP *pHead, \fBktxHashListEntry\fP *pEntry)"
.br
.RI "Delete an entry from a hash list\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxHashList_FindEntry\fP (\fBktxHashList\fP *pHead, const char *key, \fBktxHashListEntry\fP **ppEntry)"
.br
.RI "Looks up a key in a hash list and returns the entry\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxHashList_FindValue\fP (\fBktxHashList\fP *pHead, const char *key, unsigned int *pValueLen, void **ppValue)"
.br
.RI "Looks up a key in a hash list and returns the value\&. "
.ti -1c
.RI "\fBktxHashListEntry\fP * \fBktxHashList_Next\fP (\fBktxHashListEntry\fP *entry)"
.br
.RI "Returns the next entry in a \fBktxHashList\fP\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxHashList_Serialize\fP (\fBktxHashList\fP *pHead, unsigned int *pKvdLen, unsigned char **ppKvd)"
.br
.RI "Serialize a hash list to a block of data suitable for writing to a file\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxHashList_Sort\fP (\fBktxHashList\fP *pHead)"
.br
.RI "Sort a hash list in order of the UTF8 codepoints\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxHashList_Deserialize\fP (\fBktxHashList\fP *pHead, unsigned int kvdLen, void *pKvd)"
.br
.RI "Construct a hash list from a block of serialized key-value data read from a file\&. "
.in -1c
.SH "Detailed Description"
.PP 
Opaque handle to a \fBktxHashList\fP\&. 
.SH "Member Function Documentation"
.PP 
.SS "\fBKTX_error_code\fP ktxHashList_AddKVPair (\fBktxHashList\fP * pHead, const char * key, unsigned int valueLen, const void * value)"

.PP
Add a key value pair to a hash list\&. The value can be empty, i\&.e, its length can be 0\&.

.PP
\fBParameters\fP
.RS 4
\fIpHead\fP pointer to the head of the target hash list\&. 
.br
\fIkey\fP pointer to the UTF8 NUL-terminated string to be used as the key\&. 
.br
\fIvalueLen\fP the number of bytes of data in \fRvalue\fP\&. 
.br
\fIvalue\fP pointer to the bytes of data constituting the value\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS or one of the following error codes\&. 
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP if \fRpHead\fP, \fRkey\fP or \fRvalue\fP are NULL, \fRkey\fP is an empty string or \fRvalueLen\fP == 0\&. 
.RE
.PP

.SS "void ktxHashList_Construct (\fBktxHashList\fP * pHead)"

.PP
Construct an empty hash list for storing key-value pairs\&. 
.PP
\fBParameters\fP
.RS 4
\fIpHead\fP pointer to the location to write the list head\&. 
.RE
.PP

.SS "void ktxHashList_ConstructCopy (\fBktxHashList\fP * pHead, \fBktxHashList\fP orig)"

.PP
Construct a hash list by copying another\&. 
.PP
\fBParameters\fP
.RS 4
\fIpHead\fP pointer to head of the list\&. 
.br
\fIorig\fP head of the original hash list\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxHashList_Create (\fBktxHashList\fP ** ppHl)"

.PP
Create an empty hash list for storing key-value pairs\&. 
.PP
\fBParameters\fP
.RS 4
\fIppHl\fP address of a variable in which to set a pointer to the newly created hash list\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS or one of the following error codes\&. 
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_OUT_OF_MEMORY\fP\fP if not enough memory\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxHashList_CreateCopy (\fBktxHashList\fP ** ppHl, \fBktxHashList\fP orig)"

.PP
Create a copy of a hash list\&. 
.PP
\fBParameters\fP
.RS 4
\fIppHl\fP address of a variable in which to set a pointer to the newly created hash list\&. 
.br
\fIorig\fP head of the \fBktxHashList\fP to copy\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS or one of the following error codes\&. 
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_OUT_OF_MEMORY\fP\fP if not enough memory\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxHashList_DeleteEntry (\fBktxHashList\fP * pHead, \fBktxHashListEntry\fP * pEntry)"

.PP
Delete an entry from a hash list\&. 
.PP
\fBParameters\fP
.RS 4
\fIpHead\fP pointer to the head of the target hash list\&. 
.br
\fIpEntry\fP pointer to the \fBktxHashListEntry\fP to delete\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS or one of the following error codes\&. 
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP if \fRpHead\fP is NULL or \fRkey\fP is an empty string\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxHashList_DeleteKVPair (\fBktxHashList\fP * pHead, const char * key)"

.PP
Delete a key value pair in a hash list\&. Is a nop if the key is not in the hash\&.

.PP
\fBParameters\fP
.RS 4
\fIpHead\fP pointer to the head of the target hash list\&. 
.br
\fIkey\fP pointer to the UTF8 NUL-terminated string to be used as the key\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS or one of the following error codes\&. 
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP if \fRpHead\fP is NULL or \fRkey\fP is an empty string\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxHashList_Deserialize (\fBktxHashList\fP * pHead, unsigned int kvdLen, void * pKvd)"

.PP
Construct a hash list from a block of serialized key-value data read from a file\&. 
.PP
\fBNote\fP
.RS 4
The bytes of the 32-bit key-value lengths within the serialized data are expected to be in native endianness\&.
.RE
.PP
\fBParameters\fP
.RS 4
\fIpHead\fP pointer to the head of the target hash list\&. 
.br
\fIkvdLen\fP the length of the serialized key-value data\&. 
.br
\fIpKvd\fP pointer to the serialized key-value data\&. table\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS or one of the following error codes\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_OPERATION\fP\fP if \fRpHead\fP does not point to an empty list\&. 
.br
\fI\fBKTX_INVALID_VALUE\fP\fP if \fRpKvd\fP or \fRpHt\fP is NULL or kvdLen == 0\&. 
.br
\fI\fBKTX_OUT_OF_MEMORY\fP\fP there was not enough memory to create the hash table\&. 
.RE
.PP

.SS "void ktxHashList_Destroy (\fBktxHashList\fP * pHead)"

.PP
Destroy a hash list\&. All memory associated with the hash list's keys and values is freed\&. The hash list is also freed\&.

.PP
\fBParameters\fP
.RS 4
\fIpHead\fP pointer to the hash list to be destroyed\&. 
.RE
.PP

.SS "void ktxHashList_Destruct (\fBktxHashList\fP * pHead)"

.PP
Destruct a hash list\&. All memory associated with the hash list's keys and values is freed\&.

.PP
\fBParameters\fP
.RS 4
\fIpHead\fP pointer to the hash list to be destroyed\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxHashList_FindEntry (\fBktxHashList\fP * pHead, const char * key, \fBktxHashListEntry\fP ** ppEntry)"

.PP
Looks up a key in a hash list and returns the entry\&. 
.PP
\fBParameters\fP
.RS 4
\fIpHead\fP pointer to the head of the target hash list\&. 
.br
\fIkey\fP pointer to a UTF8 NUL-terminated string to find\&. 
.br
\fIppEntry\fP \fR*ppEntry\fP is set to the point at the \fBktxHashListEntry\fP\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS or one of the following error codes\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP if \fRThis\fP, \fRkey\fP or \fRpValueLen\fP or \fRppValue\fP is NULL\&. 
.br
\fI\fBKTX_NOT_FOUND\fP\fP an entry matching \fRkey\fP was not found\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxHashList_FindValue (\fBktxHashList\fP * pHead, const char * key, unsigned int * pValueLen, void ** ppValue)"

.PP
Looks up a key in a hash list and returns the value\&. 
.PP
\fBParameters\fP
.RS 4
\fIpHead\fP pointer to the head of the target hash list\&. 
.br
\fIkey\fP pointer to a UTF8 NUL-terminated string to find\&. 
.br
\fIpValueLen\fP \fR*pValueLen\fP is set to the number of bytes of data in the returned value\&. 
.br
\fIppValue\fP \fR*ppValue\fP is set to the point to the value for \fRkey\fP\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS or one of the following error codes\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP if \fRThis\fP, \fRkey\fP or \fRpValueLen\fP or \fRppValue\fP is NULL\&. 
.br
\fI\fBKTX_NOT_FOUND\fP\fP an entry matching \fRkey\fP was not found\&. 
.RE
.PP

.SS "\fBktxHashListEntry\fP * ktxHashList_Next (\fBktxHashListEntry\fP * entry)"

.PP
Returns the next entry in a \fBktxHashList\fP\&. Use for iterating through the list: 
.PP
.nf
ktxHashListEntry* entry;
for (entry = listHead; entry != NULL; entry = ktxHashList_Next(entry)) {
   \&.\&.\&.
};

.fi
.PP

.PP
Note

.PP
\fBParameters\fP
.RS 4
\fIentry\fP 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\&.
.RE
.PP
\fBReturns\fP
.RS 4
a pointer to the next entry or NULL\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxHashList_Serialize (\fBktxHashList\fP * pHead, unsigned int * pKvdLen, unsigned char ** ppKvd)"

.PP
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\&.

.PP
\fBParameters\fP
.RS 4
\fIpHead\fP pointer to the head of the target hash list\&. 
.br
\fIpKvdLen\fP \fR*pKvdLen\fP is set to the number of bytes of data in the returned data block\&. 
.br
\fIppKvd\fP \fR*ppKvd\fP is set to the point to the block of memory containing the serialized data or NULL\&. if the hash list is empty\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS or one of the following error codes\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP if \fRThis\fP, \fRpKvdLen\fP or \fRppKvd\fP is NULL\&. 
.br
\fI\fBKTX_OUT_OF_MEMORY\fP\fP there was not enough memory to serialize the data\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxHashList_Sort (\fBktxHashList\fP * pHead)"

.PP
Sort a hash list in order of the UTF8 codepoints\&. 
.PP
\fBParameters\fP
.RS 4
\fIpHead\fP pointer to the head of the target hash list\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS or one of the following error codes\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP if \fRThis\fP is NULL\&. 
.RE
.PP


.SH "Author"
.PP 
Generated automatically by Doxygen for libktx Reference from the source code\&.