libktx Reference 4.3.1
Libraries and tools to create and read KTX image texture files.
Loading...
Searching...
No Matches
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.
 
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.
 
ktxHashListEntryktxHashList_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]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 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]pHeadpointer 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]pHeadpointer to head of the list.
[in]orighead 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]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_CreateCopy()

KTX_error_code ktxHashList_CreateCopy ( ktxHashList **  ppHl,
ktxHashList  orig 
)

Create a copy of a hash list.

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

◆ ktxHashList_DeleteEntry()

KTX_error_code ktxHashList_DeleteEntry ( ktxHashList pHead,
ktxHashListEntry pEntry 
)

Delete an entry from a hash list.

Parameters
[in]pHeadpointer to the head of the target hash list.
[in]pEntrypointer to the ktxHashListEntry to delete.
Returns
KTX_SUCCESS or one of the following error codes.
Exceptions
KTX_INVALID_VALUEif 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]pHeadpointer to the head of the target hash list.
[in]keypointer 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_VALUEif 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]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_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]pHeadpointer to the head of the target hash list.
[in]keypointer 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_VALUEif This, key or pValueLen or ppValue is NULL.
KTX_NOT_FOUNDan 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]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_Next()

ktxHashListEntry * ktxHashList_Next ( ktxHashListEntry entry)

Returns the next entry in a ktxHashList.

Use for iterating through the list:

for (entry = listHead; entry != NULL; entry = ktxHashList_Next(entry)) {
...
};
Opaque handle to an entry in a ktxHashList.
ktxHashListEntry * ktxHashList_Next(ktxHashListEntry *entry)
Returns the next entry in a ktxHashList.
Definition: hashlist.c:381

Note

Parameters
[in]entrypointer 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]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 or NULL. if the hash list is empty.
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.

◆ ktxHashList_Sort()

KTX_error_code ktxHashList_Sort ( ktxHashList pHead)

Sort a hash list in order of the UTF8 codepoints.

Parameters
[in]pHeadpointer to the head of the target hash list.
Returns
KTX_SUCCESS or one of the following error codes.
Exceptions
KTX_INVALID_VALUEif This is NULL.