libdictionary/libdictionary.h File Reference

Go to the source code of this file.

Data Structures
struct	dictionary_entry_t
struct	dictionary_t
Functions
void	dictionary_init (dictionary_t *d)
	Initializes the dictionary.
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.
int	dictionary_parse (dictionary_t d, char key_value)
	Parses the key_value string and add the parsed key and value to the dictionary.
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.
void	dictionary_destroy (dictionary_t *d)
	Frees any memory associated with the dictionary.
Variables
const int	NO_KEY_EXISTS
	Return value if no key exists in the dictionary.
const int	KEY_EXISTS
	Return value if a key exists in the dictionary.
const int	ILLEGAL_FORMAT
	Return value if the format of the input is illegal.

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. (You should NOT use strcpy() in the function at all.)

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	A pointer to an initalized 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.

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.

(Since d was provided for you by the programmer and not something you created, you should NOT free d itself. Only free member elements of the data structure.)

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.

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 )

Initializes the dictionary.

(If your data structure does not require any initialization logic, this function may be empty.)

You may assume that:

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

Parameters:

d

A pointer to the dictionary. Since all values are passed by value in C, you should never directly modify the parameter d. For example:

     d = malloc( sizeof(dictionary_t) );
     ...

...will not change d when d is returned to the caller. Instead, you should modify only the members of the structure that is pointed to by d, such as:

     d->entry = malloc( sizeof(dictionary_entry_t) );
     d->entry->value = ...
     ...

int dictionary_parse	(	dictionary_t *	d,
		char *	key_value
	)

Parses the key_value string and add the parsed key and value to the dictionary.

This function must make a call to dictionary_add() when adding to the dictionary.

The format of the key_value will be the format of an HTTP header (you can read more aboud the headers here, but this is not necessary to understand ), where the contents will be the KEY (one or more non-colon characters), a colon, a single space, and the rest will be the VALUE. (While the KEY cannot be an empty string, it is possible for the VALUE to be an empty string.)

This function should NOT copy key_value and should NOT create any additional memory to store the KEY and VALUE pieces of the string. Instead, this function should modify the key_value string in-place, if necessary. If the function fails, key_value should be unmodified.

Valid inputs:

"Host: www.cs.uiuc.edu"
"MyKey: MyValue"
"a: b"
"SomeLongKey: ", where there is a trailing space after the colon
"Strange: but:this:is:okay: and: so: is: this"
"e: :e"
"This is not common: but it's not illegal"
"Strange: case", where the value would be " case"

Illegal inputs:

": www.cs.uiuc.edu", since the KEY is zero-length
"MyKey, MyValue", since no colon, space exists
"a:b", since no colon, space exists.
"a:: b", since the first colon isn't followed by a space.

You may assume that:

All whitespace surrounding key_value has been removed.
The parameters will be valid, non-NULL pointers.

Parameters:

	d	A pointer to an initalized dictionary data structure.
	key_value	The key-value pair that is to be parsed and added to the dictionary.

Return values:

	0	Success (the key_value was parsed and added to the dictionary) KEY_EXISTS The dictionary already contains a key with the same name as the KEY in key_value
	ILLEGAL_FORMAT	The format of key_value is illegal.