smf_dict.h File Reference

Defines the SMFDict_T data type and functions for a dictionary. More...

#include "smf_list.h"

Include dependency graph for smf_dict.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	SMFDict_T
	Dictionary data type. More...

Macros
#define	smf_dict_count(dict)   ((dict)->n)
	Get the number of elements in a SMFDict_T.

Functions
SMFDict_T *	smf_dict_new (void)
	Create a new SMFDict_T.
void	smf_dict_free (SMFDict_T *dict)
	Frees a SMFDict_T with all keys and values.
int	smf_dict_set (SMFDict_T *dict, const char *key, const char *val)
	Inserts a key and value into a SMFDict_T.
char *	smf_dict_get (SMFDict_T *dict, const char *key)
	Looks up a key in a SMFDict_T and get the associated value.
unsigned long	smf_dict_get_ulong (SMFDict_T *dict, const char *key, int *success)
	Looks up a key in a SMFDict_T and get the associated unsigned long value (if possible). The function tries to convert to value behind the key into a unsigned long value, returns it and sets the success-pointer to 1. If the key does not exists or if the convertion is not possible, then (unsigned long)-1 is returned and the success-pointer is set to 0.
void	smf_dict_remove (SMFDict_T *dict, const char *key)
	Removes a key and its associated value from a SMFDict_T.
SMFList_T *	smf_dict_get_keys (SMFDict_T *dict)
	Retrieves every key inside a SMFDict_T.
void	smf_dict_map (SMFDict_T *dict, void(*func)(char *key, char *value, void *args), void *args)
	Calls the given function for each of the key/value pairs in the SMFDict_T. The function is passed the key and value of each pair, and the given args parameter.

Detailed Description

Defines the SMFDict_T data type and functions for a dictionary.

A SMFDict_T provides associations between keys and values so that given a key, the associated value can be found very quickly. Please note that the keys and values are copied when inserted into the dictionary and will be freed with smf_dict_free()

To create a new SMFDict_T, use smf_dict_new()

To insert a key and value into a SMFDict_T, use smf_dict_set()

To lookup a value corresponding to a given key, use smf_dict_get()

To remove a key and value, use smf_dict_remove()

To call a function for each key and value pair use smf_dict_map()

To destroy a SMFDict_T use smf_dict_free()

Macro Definition Documentation

#define smf_dict_count

(

dict

)

((dict)->n)

Get the number of elements in a SMFDict_T.

Returns

number of elemtents in a SMFDict_T

Function Documentation

void smf_dict_free

(

SMFDict_T *

dict

)

Frees a SMFDict_T with all keys and values.

Parameters

dict	SMFDict_T to deallocate.

char* smf_dict_get	(	SMFDict_T *	dict,
		const char *	key
	)

Looks up a key in a SMFDict_T and get the associated value.

Parameters

dict	a SMFDict_T object
key	key to look for in the dictionary.

Returns

the associated value, or NULL if the key is not found

SMFList_T* smf_dict_get_keys

(

SMFDict_T *

dict

)

Retrieves every key inside a SMFDict_T.

Parameters

dict	a SMFDict_T object

Returns

a SMFList_T containing all the keys inside the dictionary. Use smf_list_free() when done using the list.

unsigned long smf_dict_get_ulong	(	SMFDict_T *	dict,
		const char *	key,
		int *	success
	)

Looks up a key in a SMFDict_T and get the associated unsigned long value (if possible). The function tries to convert to value behind the key into a unsigned long value, returns it and sets the success-pointer to 1. If the key does not exists or if the convertion is not possible, then (unsigned long)-1 is returned and the success-pointer is set to 0.

Parameters

dict	a SMFDict_T object
key	key to look for in the dictionary.
success	If set to non-NULL, then the function assigns here the result of the conversion

Returns

The unsigned long value of the key or (unsigned long)-1 on any error.

void smf_dict_map	(	SMFDict_T *	dict,
		void(*)(char *key, char *value, void *args)	func,
		void *	args
	)

Calls the given function for each of the key/value pairs in the SMFDict_T. The function is passed the key and value of each pair, and the given args parameter.

Parameters

dict	a SMFDict_T object
func	function to call for each element
args	optional arguments to pass to the function

SMFDict_T* smf_dict_new

(

void

)

Create a new SMFDict_T.

Returns

a newly allocated SMFDict_T.

void smf_dict_remove	(	SMFDict_T *	dict,
		const char *	key
	)

Removes a key and its associated value from a SMFDict_T.

Parameters

dict	a SMFDict_T
key	the key to remove.

int smf_dict_set	(	SMFDict_T *	dict,
		const char *	key,
		const char *	val
	)

Inserts a key and value into a SMFDict_T.

If the given key is found in the dictionary, the associated value is replaced by the provided one. If the key cannot be found in the dictionary, it will be added to it.

Parameters

dict	a SMFDict_T object to modify.
key	key to modify or add.
val	Value to add.

Returns

0 on success or -1 in case of error