libdictionary.c File Reference

#include <search.h>
#include <stdlib.h>
#include <string.h>
#include <pthread.h>
#include "libdictionary.h"

Functions
void	dictionary_init (dictionary_t *d)
	Initialize the dictionary data structure.
int	dictionary_add (dictionary_t *d, const char *key, const char *value)
	Adds the key-value pair (key, value) to the dictionary, if and only if the dictionary does not already contain a key with the same name as key.
const char *	dictionary_get (dictionary_t *d, const char *key)
	Returns the value of the key-value element for a specific key.
int	dictionary_remove (dictionary_t *d, const char *key)
	Removes the key-value pair for a given key from the dictionary, if it exists.
int	dictionary_remove_free (dictionary_t *d, const char *key)
	Removes the key-value pair for a given key from the dictionary, if it exists, and free()s the key and value strings for the user.
void	dictionary_destroy (dictionary_t *d)
	Frees any memory associated with the dictionary.
void	dictionary_destroy_free (dictionary_t *d)
	Frees any memory associated with the dictionary.

---

Detailed Description

---

Function Documentation

int dictionary_add	(	dictionary_t *	d,
		const char *	key,
		const char *	value
	)

Adds the key-value pair (key, value) to the dictionary, if and only if the dictionary does not already contain a key with the same name as key.

This function does NOT make a copy of the key or value.

This function is thread-safe.

You may assume that:

• The stirngs key and value will not be modified outside of the dictionary.
• The parameters will be valid, non-NULL pointers.

Parameters:

	d	Dictionary data structure.
	key	The key to be added to the dictionary.
	value	The value to be assoicated with the key in the dictionary.

Return values:

	0	Success
	KEY_EXISTS	The dictionary already contains they specified key.

void dictionary_destroy

(

dictionary_t *

d

)

Frees any memory associated with the dictionary.

This function does not free() any keys or values of the elements contained in the dictionary.

See also:

dictionary_destroy_free()

You may assume that:

• This function will only be called once per dicitonary_t instance.
• This function will be the last function called on each dictionary_t instance.
• The dictionary pointer will be valid, non-NULL pointer.

Parameters:

d

A pointer to an initalized dictionary data structure.

void dictionary_destroy_free

(

dictionary_t *

d

)

Frees any memory associated with the dictionary.

Additionally, this function will free() the key and value strings of all entries that still exist in the dictionary. To free only the internal memory to the dictionary,

See also:

dictionary_destroy().

You may assume that:

• This function will only be called once per dicitonary_t instance.
• This function will be the last function called on each dictionary_t instance.
• The dictionary pointer will be valid, non-NULL pointer.

Parameters:

d

A pointer to an initalized dictionary data structure.

const char* dictionary_get	(	dictionary_t *	d,
		const char *	key
	)

Returns the value of the key-value element for a specific key.

If the key does not exist, this function returns NULL.

This function is thread-safe.

You may assume that:

• The parameters will be valid, non-NULL pointers.

Parameters:

	d	A pointer to an initalized dictionary data structure.
	key	The key to lookup in the dictionary.

Returns:

• the value of the key-value element, if the key exists in the dictionary
• NULL, otherwise.

void dictionary_init

(

dictionary_t *

d

)

Initialize the dictionary data structure.

This function must be called before any other libdictionary functions.

Parameters:

d

Dictionary data structure.

int dictionary_remove	(	dictionary_t *	d,
		const char *	key
	)

Removes the key-value pair for a given key from the dictionary, if it exists.

This function will not free() the key or value.

See also:

dictionary_remove_free()

You may assume that:

• The parameters will be valid, non-NULL pointers.

Parameters:

	d	A pointer to an initalized dictionary data structure.
	key	The key to remove from the dictionary.

Return values:

	0	Success.
	NO_KEY_EXISTS	The dictionary did not contain key.

int dictionary_remove_free	(	dictionary_t *	d,
		const char *	key
	)

Removes the key-value pair for a given key from the dictionary, if it exists, and free()s the key and value strings for the user.

You may assume that:

• The parameters will be valid, non-NULL pointers.

Parameters:

	d	A pointer to an initalized dictionary data structure.
	key	The key to remove from the dictionary.

Return values:

	0	Success.
	NO_KEY_EXISTS	The dictionary did not contain key.