Dictionaries

Nestable dictionary keyed on strings. More...

Functions
dpl_dict_t *	dpl_dict_new (int n_buckets)
	Create a new dict. More...
dpl_dict_var_t *	dpl_dict_get (const dpl_dict_t *dict, const char *key)
	Lookup an entry. More...
dpl_status_t	dpl_dict_get_lowered (const dpl_dict_t *dict, const char *key, dpl_dict_var_t **varp)
	Lookup an entry using a lowered key. More...
dpl_status_t	dpl_dict_iterate (const dpl_dict_t *dict, dpl_dict_func_t cb_func, void *cb_arg)
	Iterate the entries of a dict. More...
int	dpl_dict_count (const dpl_dict_t *dict)
	Count entries in a dict. More...
void	dpl_dict_free (dpl_dict_t *dict)
	Free a dict. More...
void	dpl_dict_print (const dpl_dict_t *dict, FILE *f, int level)
	Print the contents of a dict. More...
dpl_status_t	dpl_dict_add_value (dpl_dict_t *dict, const char *key, dpl_value_t *value, int lowered)
	Add or replace an entry. More...
dpl_status_t	dpl_dict_add (dpl_dict_t *dict, const char *key, const char *string, int lowered)
	Add or replace a string entry. More...
dpl_status_t	dpl_dict_copy (dpl_dict_t *dst, const dpl_dict_t *src)
	Copy all entries from one dict to another. More...
dpl_dict_t *	dpl_dict_dup (const dpl_dict_t *src)
	Duplicate a dict. More...
dpl_status_t	dpl_dict_filter_prefix (dpl_dict_t *dst, const dpl_dict_t *src, const char *prefix)
	Copy entries matching a prefix from one dict to another. More...
dpl_status_t	dpl_dict_filter_no_prefix (dpl_dict_t *dst, const dpl_dict_t *src, const char *prefix)
	Copy entries not matching a prefix from one dict to another. More...
char *	dpl_dict_get_value (const dpl_dict_t *dict, const char *key)
	Lookup a string-valued entry. More...

Detailed Description

The dpl_dict_t structure is a simple key/value dictionary. Keys are strings, and values may be strings, vectors, or nested dicts. Entries are unique for a given key; adding a second entry with a matching key silently replaces the original.

Dicts are implemented with a chained hash table for efficiency.

Dicts are used within Droplet to store all kinds of data, but in particular collections of user metadata strings (which map naturally to key/value string pairs).

Function Documentation

dpl_status_t dpl_dict_add	(	dpl_dict_t *	dict,
		const char *	key,
		const char *	string,
		int	lowered
	)

Adds to the dict a new entry keyed by key with a string value string. If the dict already contains an entry with the same key, the old entry is replaced. Both key and string are copied.

Parameters

dict	the dict to add an entry to
key	the key for the new entry
string	the new value to be entered
lowered	if nonzero, key is converted to lower case

Return values

DPL_SUCCESS	on success, or
DPL_*	a Droplet error code on failure

dpl_status_t dpl_dict_add_value	(	dpl_dict_t *	dict,
		const char *	key,
		dpl_value_t *	value,
		int	lowered
	)

Adds to the dict a new entry keyed by key with value value. If the dict already contains an entry with the same key, the old entry is replaced. Both key and value are copied. If the value is a string, you should use dpl_dict_add() which is a more convenient interface.

Parameters

dict	the dict to add an entry to
key	the key for the new
value	the new value to be entered
lowered	if nonzero, key is converted to lower case

Return values

DPL_SUCCESS	on success, or
DPL_*	a Droplet error code on failure

dpl_status_t dpl_dict_copy	(	dpl_dict_t *	dst,
		const dpl_dict_t *	src
	)

Copies all the entries from dict src to dict dst. If dst contains entries which match entries in src, those entries will be replaced.

Parameters

dst	the dict to copy entries to
src	the dict to copy entries from

Return values

DPL_SUCCESS	on success, or
DPL_*	a Droplet error code on failure

int dpl_dict_count

(

const dpl_dict_t *

dict

)

Counts and returns the number of entries in the dict.

Parameters

dict	the dict whose entries are to be counted

Returns

the number of entries in the dict

dpl_dict_t* dpl_dict_dup

(

const dpl_dict_t *

src

)

Creates and returns a new dict containing copies of all the entries from the dict src. You should call dpl_dict_free() to free the dict when you have finished using it.

Parameters

src	the dict to copy entries from

Returns

a new dict or NULL on failure

dpl_status_t dpl_dict_filter_no_prefix	(	dpl_dict_t *	dst,
		const dpl_dict_t *	src,
		const char *	prefix
	)

Copies to dict dst all the entries from dict src whose keys do NOT match the string prefix prefix. The comparison is case sensitive. If dst contains entries which match entries in src, those entries will be replaced.

Note

if src is NULL, dst will be freed. This may be surprising.

Parameters

dst	the dict to copy entries to
src	the dict to copy entries from
prefix	a string prefix for comparing to keys

Return values

DPL_SUCCESS	on success, or
DPL_*	a Droplet error code on failure

dpl_status_t dpl_dict_filter_prefix	(	dpl_dict_t *	dst,
		const dpl_dict_t *	src,
		const char *	prefix
	)

Copies to dict dst all the entries from dict src whose keys match the string prefix prefix. The comparison is case sensitive. If dst contains entries which match entries in src, those entries will be replaced.

Note

if src is NULL, dst will be freed. This may be surprising.

Parameters

dst	the dict to copy entries to
src	the dict to copy entries from
prefix	a string prefix for comparing to keys

Return values

DPL_SUCCESS	on success, or
DPL_*	a Droplet error code on failure

void dpl_dict_free

(

dpl_dict_t *

dict

)

Free the dict and all its entries.

Parameters

dict	the dict to free

dpl_dict_var_t* dpl_dict_get	(	const dpl_dict_t *	dict,
		const char *	key
	)

Looks up and returns an entry in the dict matching key key exactly, or NULL if no matching entry is found. The val field in the returned dpl_dict_var_t structure points to a dpl_value_t which contains the stored value. If you know beforehand that the value will be a string, you should call dpl_dict_get_value() instead, as it's a more convenient interface.

Parameters

dict	the dict to look up
key	the key to look up

Returns

the entry matching key if found, or NULL

dpl_status_t dpl_dict_get_lowered	(	const dpl_dict_t *	dict,
		const char *	key,
		dpl_dict_var_t **	varp
	)

Looks up and returns an entry in the dict matching a lower case version of key.

Parameters

	dict	the dict to look up in
	key	the key to look up
[out]	varp	if a matching entry is found, *varp will be changed to point at it

Return values

DPL_SUCCESS	on success, or
DPL_ENOENT	if no matching entry is found, or
DPL_*	other Droplet error codes on failure

char* dpl_dict_get_value	(	const dpl_dict_t *	dict,
		const char *	key
	)

Looks up an entry in the dict matching key key exactly, and returns the entry's value string or NULL if no matching entry is found. The returned string is owned by the dict, do not free it.

A found entry must be string valued, or this function will fail an assert. Use dpl_dict_get() for the more general case where the entry can be other types than a string.

Parameters

dict	the dict to look up
key	the key to look up

Returns

the matching entry's value if found, or NULL

dpl_status_t dpl_dict_iterate	(	const dpl_dict_t *	dict,
		dpl_dict_func_t	cb_func,
		void *	cb_arg
	)

Calls the callback function cb_func once for each entry in the dict. The callback may safely add or delete entries from the dict; newly added entries may or may not be seen during the iteration.

The callback returns a Droplet error code; if it returns any code other than DPL_SUCCESS iteration ceases immediately and that code is returned from dpl_dict_iterate(). The callback function should be declared like this

dpl_status_t
my_callback(dpl_dict_var_t *var, void *cb_arg)
{
   const char *key = var->key;
   dpl_value_t *val = var->val;
   return DPL_SUCCESS;  // keep iterating
}

Parameters

dict	the dict whose entries will be iterated
cb_func	callback function to call
cb_arg	opaque pointer passed to callback function

Return values

DPL_SUCCESS	on success, or
DPL_*	a Droplet error code returned by the callback function

dpl_dict_t* dpl_dict_new

(

int

n_buckets

)

Creates and returns a new dpl_dict_t object. The n_buckets parameter controls how many hash buckets the dict will use, which is fixed for the lifetime of the dict but does not affect the dict's capacity, only it's performance. Typically a prime number like 13 is a good choice for small dicts. You should call dpl_dict_free() to free the dict when you have finished using it.

Parameters

n_buckets

specifies how many buckets the dict will use

Returns

a new dict, or NULL on failure

void dpl_dict_print	(	const dpl_dict_t *	dict,
		FILE *	f,
		int	level
	)

Prints the keys and values of all entries in the dict in a human readable format with indenting. Handles non-string values; in particular vectors and nested dicts. This function is useful only for debugging, as there is no ability to read this information back into a dict.

Parameters

dict	the dict whose entries are to be printed
f	a stdio file to which to print the entries
level	you should pass 0 for this argument