PSC_Dictionary Class Reference

A dictionary storing any data objects using any type of keys. More...

#include <poser/core/dictionary.h>

Public Member Functions
PSC_Dictionary *	PSC_Dictionary_create (void(*deleter)(void *))
	PSC_Dictionary default constructor.
void	PSC_Dictionary_set (PSC_Dictionary *self, const void *key, size_t keysz, void *obj, void(*deleter)(void *))
	Set a new object for a given key.
void *	PSC_Dictionary_get (const PSC_Dictionary *self, const void *key, size_t keysz)
	Retrieve a stored object by its key.
size_t	PSC_Dictionary_count (const PSC_Dictionary *self)
	The total number of stored objects.
size_t	PSC_Dictionary_removeAll (PSC_Dictionary *self, int(*matcher)(const void *, size_t, void *, const void *), const void *arg)
	Remove all matching entries from dictionary.
void	PSC_Dictionary_destroy (PSC_Dictionary *self)
	PSC_Dictionary destructor.

Static Public Attributes
DECLDATA void(*	PSC_DICT_NODELETE )(void *)
	Dummy deleter, indicating entries should not be deleted.

Detailed Description

A dictionary storing any data objects using any type of keys.

Keys are interpreted as arrays of bytes of a specified size, so any object stored in contiguous memory can be used as a key. For a string key, just pass the string length as the size.

This works internally as a structure of nested hash tables. A 64bit hash function (currently xxHash 3) is used to calculate a hash of the given key. The root of a PSC_Dictionary is a hash table with 256 entries, using the lowest 8 bits of the hash. On collissions, a second level hash table with another 256 entries is created, using the next 8 bits of the hash.

Further collissions in a second-level table will create more child tables, but only with 16 entries, using another 4 bits of the hash, which is repeated until there are no bits of the hash left. If this is ever reached, collissions are resolved using a linked list for the affected bucket of the innermost hash table.

Member Function Documentation

PSC_Dictionary_count()

size_t PSC_Dictionary_count

(

const PSC_Dictionary *

self

)

The total number of stored objects.

Parameters

self	the PSC_Dictionary

Returns

the number of objects stored

PSC_Dictionary_create()

PSC_Dictionary * PSC_Dictionary_create

(

void(*)(void *)

deleter

)

PSC_Dictionary default constructor.

Creates a new PSC_Dictionary

Parameters

deleter

Function to delete stored objects when they are removed, replaced or the PSC_Dictionary is destroyed. If this is given as NULL, individual deletion functions can be passed to PSC_Dictionary_set(), otherwise functions passed there are ignored. Can be set to the special value PSC_DICT_NODELETE to completely disable deletion of stored objects for the whole PSC_Dictionary.

Returns

a newly created PSC_Dictionary

PSC_Dictionary_destroy()

void PSC_Dictionary_destroy

(

PSC_Dictionary *

self

)

PSC_Dictionary destructor.

Stored objects are also destructed if a global deleter is set or they have individual deleters attached.

Parameters

self	the PSC_Dictionary

PSC_Dictionary_get()

void * PSC_Dictionary_get	(	const PSC_Dictionary *	self,
		const void *	key,
		size_t	keysz
	)

Retrieve a stored object by its key.

Parameters

self	the PSC_Dictionary
key	the key
keysz	the size of the key

Returns

the object stored for the given key, or NULL if not found

PSC_Dictionary_removeAll()

size_t PSC_Dictionary_removeAll	(	PSC_Dictionary *	self,
		int(*)(const void *, size_t, void *, const void *)	matcher,
		const void *	arg
	)

Remove all matching entries from dictionary.

Parameters

self	the PSC_Dictionary
matcher	function to check each entry, given by its key, the key size and the stored object itself, according to some specified argument. Must return 1 to have the entry removed, 0 to leave it.
arg	some argument for the matcher function

Returns

the number of entries removed

PSC_Dictionary_set()

void PSC_Dictionary_set	(	PSC_Dictionary *	self,
		const void *	key,
		size_t	keysz,
		void *	obj,
		void(*)(void *)	deleter
	)

Set a new object for a given key.

If the key already exists, the associated object is replaced.

Parameters

self	the PSC_Dictionary
key	the key
keysz	the size of the key
obj	the new object to store, or NULL to remove the object for the given key
deleter	Individual deletion function for the stored object, ignored if the dictionary was constructed with global deleter.

---

The documentation for this class was generated from the following file:

• poser/core/dictionary.h