s2dict.h File Reference

The dict key-value mapping contaier type. More...

#include "s2obj.h"
#include "s2data.h"
#include "s2containers.h"

Macros
#define	s2_is_dict(obj)
#define	s2dict_get_T(membertype)

Typedefs
typedef T	s2dict_t
	the working context for the dict type s2dict_t. In the following prose, s2dict_t will be abbreviated as T.
typedef struct s2ctx_dict_iter	s2dict_iter_t
	the dictionary iterator type that enumerates members in arbitrary order.

Functions
void	siphash_setkey (void const *restrict in, size_t inlen)
	Sets the randomization vector for hash tables globally.
T *	s2dict_create ()
	Creates and returns an empty dictionary map.
int	s2dict_get (T *dict, s2data_t *key, s2obj_t **out)
int	s2dict_set (T *dict, s2data_t *key, s2obj_t *value, int semantic)
int	s2dict_unset (T *dict, s2data_t *key)
	unsets a key from a dict.

Detailed Description

The dict key-value mapping contaier type.

Macro Definition Documentation

s2_is_dict

#define s2_is_dict

(

obj

)

Value:

(((s2obj_t *)obj)->type == S2_OBJ_TYPE_DICT)

Parameters

obj	the object handle the type of which is being checked.

Returns

true if the object handle of dict type, false otherwise.

s2dict_get_T

#define s2dict_get_T

(

membertype

)

Value:

    ((int (*)(s2dict_t *dict, s2data_t *key, membertype **out))s2dict_get)

Parameters

membertype

the type of the object the handle would point to.

The type-safe method to get a value object without type casting. Invoked as: s2dict_get_T(type)(dict, key, out). Defined as a marcro in terms of s2dict_get.

Function Documentation

s2dict_create()

T * s2dict_create

(

)

Creates and returns an empty dictionary map.

Returns

a pointer to the dict object handle, or NULL on error.

s2dict_get()

int s2dict_get	(	T *	dict,
		s2data_t *	key,
		s2obj_t **	out )

Parameters

dict	the dict from which a member is retrieved using a data key.
key	the said data key.
out	the pointer to the object handle where the retrieved object will be stored.

''refcnt'' and ''keptcnt'' are not incremented, because they're still available from the dict (i.e. not unset). They have to be explicitly retained.

Returns

s2_access_success is returned when an object is successfully retrieved. s2_access_nullval is returned on success, when the key is unset. s2_access_error is returned on error. See s2containers.h for further detail.

s2dict_set()

int s2dict_set	(	T *	dict,
		s2data_t *	key,
		s2obj_t *	value,
		int	semantic )

Parameters

dict	the dict to which a value object will be set using a data key.
key	the said key.
value	the said value object.
semantic	the setter semantic, see file s2containers.h.

Sets a value object into dict at key. If there exists a value at the key, it's first released by s2obj_leave.

If semantic is s2_setter_kept, then reference count stays the same while kept count is incremented. If semantic is s2_setter_gave, then reference count is decremented while kept count is incremented. See s2containers.h for further detail.

Returns

s2_access_success is returned when an object is successfully retrieved. s2_access_error is returned on error. See s2containers.h for further detail.

s2dict_unset()

int s2dict_unset	(	T *	dict,
		s2data_t *	key )

unsets a key from a dict.

Parameters

dict	the dict from which a key will be unset.
key	the key to unset.

Returns

s2_access_success is returned when an object is successfully retrieved. s2_access_error is returned on error. See s2containers.h for further detail.

siphash_setkey()

void siphash_setkey	(	void const *restrict	in,
		size_t	inlen )

Sets the randomization vector for hash tables globally.

Parameters

in	the randomization vector data.
inlen	the length of the data.