420 lines
11 KiB
Plaintext
420 lines
11 KiB
Plaintext
.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\&.
|