collection.h File Reference

A Keyed Collection Implementation. More...

#include "common.h"

Go to the source code of this file.

Data Structures
struct	qsc_collection_state
	Collection state structure. More...

Macros
#define	QSC_COLLECTION_KEY_WIDTH   16ULL
	The length (in bytes) of the key used to index collection items.

Functions
QSC_EXPORT_API void	qsc_collection_add (qsc_collection_state *ctx, const uint8_t *item, const uint8_t *key)
	Add an item to the collection.
QSC_EXPORT_API void	qsc_collection_deserialize (qsc_collection_state *ctx, const uint8_t *input)
	Deserialize a collection.
QSC_EXPORT_API void	qsc_collection_dispose (qsc_collection_state *ctx)
	Dispose of the collection.
QSC_EXPORT_API void	qsc_collection_erase (qsc_collection_state *ctx)
	Erase the collection.
QSC_EXPORT_API bool	qsc_collection_item_exists (const qsc_collection_state *ctx, const uint8_t *key)
	Check if an item exists in the collection.
QSC_EXPORT_API bool	qsc_collection_find (const qsc_collection_state *ctx, uint8_t *item, const uint8_t *key)
	Find an item in the collection.
QSC_EXPORT_API void	qsc_collection_initialize (qsc_collection_state *ctx, size_t width)
	Initialize the collection.
QSC_EXPORT_API void	qsc_collection_item (qsc_collection_state *ctx, uint8_t *item, size_t index)
	Retrieve a collection item by index.
QSC_EXPORT_API void	qsc_collection_remove (qsc_collection_state *ctx, const uint8_t *key)
	Remove an item from the collection.
QSC_EXPORT_API size_t	qsc_collection_serialize (uint8_t *output, const qsc_collection_state *ctx)
	Serialize the collection.
QSC_EXPORT_API size_t	qsc_collection_size (const qsc_collection_state *ctx)
	Get the serialized collection size.

Detailed Description

A Keyed Collection Implementation.

This header defines the public API for a keyed collection that facilitates the storage, retrieval, and management of items associated with unique keys. Items are stored in a contiguous memory block with a fixed width (in bytes) specified at initialization. The API supports operations such as adding, removing, finding, serializing, and disposing of items.

Example:

#include "collection.h"
 
qsc_collection_state col;
// Initialize the collection with a fixed item size (e.g., 32 bytes).
qsc_collection_initialize(&col, 32);
 
uint8_t sample_item[32] = { item data };
uint8_t sample_key[QSC_COLLECTION_KEY_WIDTH] = { key data };
 
// Add an item to the collection.
qsc_collection_add(&col, sample_item, sample_key);
 
// Check if an item exists using its key.
if (qsc_collection_item_exists(&col, sample_key))
{
    uint8_t retrieved[32];
    qsc_collection_find(&col, retrieved, sample_key);
}
 
// Serialize the collection.
size_t serialized_size = qsc_collection_size(&col);
uint8_t* serialized = (uint8_t*)malloc(serialized_size);
qsc_collection_serialize(serialized, &col);
 
// Dispose of the collection and free the serialized data.
qsc_collection_dispose(&col);
free(serialized);

Function Documentation

qsc_collection_add()

QSC_EXPORT_API void qsc_collection_add	(	qsc_collection_state *	ctx,
		const uint8_t *	item,
		const uint8_t *	key )

Add an item to the collection.

Adds a new item to the collection and associates it with the specified key.

Parameters

ctx	[qsc_collection_state*] Pointer to the collection state.
item	[const uint8_t*] Pointer to the item data to be added.
key	[const uint8_t*] Pointer to the key that uniquely identifies the item.

qsc_collection_deserialize()

QSC_EXPORT_API void qsc_collection_deserialize	(	qsc_collection_state *	ctx,
		const uint8_t *	input )

Deserialize a collection.

Converts a serialized byte array into a collection state.

Parameters

ctx	[qsc_collection_state*] Pointer to the collection state that will be populated.
input	[const uint8_t*] Pointer to the serialized collection data.

qsc_collection_dispose()

QSC_EXPORT_API void qsc_collection_dispose

(

qsc_collection_state *

ctx

)

Dispose of the collection.

Frees any allocated memory and clears the collection state.

Parameters

ctx	[qsc_collection_state*] Pointer to the collection state to dispose.

qsc_collection_erase()

QSC_EXPORT_API void qsc_collection_erase

(

qsc_collection_state *

ctx

)

Erase the collection.

Removes all items from the collection without deallocating the underlying storage.

Parameters

ctx	[qsc_collection_state*] Pointer to the collection state to erase.

qsc_collection_find()

QSC_EXPORT_API bool qsc_collection_find	(	const qsc_collection_state *	ctx,
		uint8_t *	item,
		const uint8_t *	key )

Find an item in the collection.

Searches for an item by its key and copies it into the provided output buffer.

Parameters

ctx	[const qsc_collection_state*] Pointer to the collection state.
item	[uint8_t*] Pointer to the destination array that will receive the item data.
key	[const uint8_t*] Pointer to the key of the item to find.

Returns

[bool] Returns true if the item was found; otherwise, false.

qsc_collection_initialize()

QSC_EXPORT_API void qsc_collection_initialize	(	qsc_collection_state *	ctx,
		size_t	width )

Initialize the collection.

Sets up the collection state for use by specifying the byte size of each item.

Parameters

ctx	[qsc_collection_state*] Pointer to the collection state to initialize.
width	[size_t] The fixed byte size of each item in the collection.

qsc_collection_item()

QSC_EXPORT_API void qsc_collection_item	(	qsc_collection_state *	ctx,
		uint8_t *	item,
		size_t	index )

Retrieve a collection item by index.

Copies the item at the specified index into the provided output buffer.

Parameters

ctx	[qsc_collection_state*] Pointer to the collection state.
item	[uint8_t*] Pointer to the array that will receive the item data.
index	[size_t] The zero-based index of the item to retrieve.

qsc_collection_item_exists()

QSC_EXPORT_API bool qsc_collection_item_exists	(	const qsc_collection_state *	ctx,
		const uint8_t *	key )

Check if an item exists in the collection.

Determines whether an item with the specified key exists in the collection.

Parameters

ctx	[const qsc_collection_state*] Pointer to the collection state.
key	[const uint8_t*] Pointer to the key of the item to check.

Returns

[bool] Returns true if the item exists; otherwise, false.

qsc_collection_remove()

QSC_EXPORT_API void qsc_collection_remove	(	qsc_collection_state *	ctx,
		const uint8_t *	key )

Remove an item from the collection.

Removes the item associated with the specified key from the collection.

Parameters

ctx	[qsc_collection_state*] Pointer to the collection state.
key	[const uint8_t*] Pointer to the key of the item to remove.

qsc_collection_serialize()

QSC_EXPORT_API size_t qsc_collection_serialize	(	uint8_t *	output,
		const qsc_collection_state *	ctx )

Serialize the collection.

Converts the entire collection into a contiguous byte array for storage or transmission.

Parameters

output	[uint8_t*] Pointer to the output buffer that will receive the serialized data.
ctx	[const qsc_collection_state*] Pointer to the collection state.

Returns

[size_t] Returns the size in bytes of the serialized collection.

qsc_collection_size()

QSC_EXPORT_API size_t qsc_collection_size

(

const qsc_collection_state *

ctx

)

Get the serialized collection size.

Calculates the total size in bytes that the serialized collection will occupy.

Parameters

ctx	[const qsc_collection_state*] Pointer to the collection state.

Returns

[size_t] Returns the byte size of the serialized collection.