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_Tsmf_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_Tsmf_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
dictSMFDict_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
dicta SMFDict_T object
keykey 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
dicta 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
dicta SMFDict_T object
keykey to look for in the dictionary.
successIf 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
dicta SMFDict_T object
funcfunction to call for each element
argsoptional 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
dicta SMFDict_T
keythe 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
dicta SMFDict_T object to modify.
keykey to modify or add.
valValue to add.
Returns
0 on success or -1 in case of error