/simpletypesystem/trunk

/*

    (C) Gustav Hartvigsson, 2013.

    This program is free software: you can redistribute it and/or modify

    it under the terms of the GNU Lesser General Public License as

    published by the Free Software Foundation, either version 3 of the

    License.

    This program is distributed in the hope that it will be useful,

    but WITHOUT ANY WARRANTY; without even the implied warranty of

    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License

    along with this program.  If not, see <http://www.gnu.org/licenses/>.

*/

#ifndef __H_MAP__

#define __H_MAP__

/**

 * An SMap is a data structure that holds many mappings of objects to objects:

 * say, a string to an other string. This can be likened to the Dict structure

 * in python, but not fully.

 * 

 * An SMap is made up of SMapItems, each MapItem holds two pointers to data.

 * The first pointer is the key, the secold is the value.

 *

 * please note that SMaps can be slow and are unordered.

 *

 * @file

 */

#include "baseobject.h"

#include "Func.h"

#include <stdbool.h>

/** @brief

 * SMapItem holds the mapping of a key to a value.

 */

typedef struct _SMapItem SMapItem;

/** @brief

 * An SMap is a map many SMapItems. Mapping between a key and a value.

 * 

 * functions:

 * * \c s_map_new \c ()

 * * \c s_map_free \c ()

 * * \c s_map_add \c ()

 * * \c s_map_get \c ()

 */

typedef struct _SMap SMap;

typedef struct _SMapClass SMapClass;

typedef struct _SMapPrivate SMapPrivate;

/**

 * Data structure representing an SMapItem

 */

struct _SMapItem {

  void * key; /**< The Key */

  void * value; /**< The Value */

};

/** @brief

 * Data structure representing an SMap

 */

struct _SMap {

  SBaseObjectInstance parent; /**< The parent instance */

  SMapPrivate * priv; /**< Private data pointer */

};

struct _SMapClass {

  SBaseObjectClass parentclass;

  CompFunc is_equal; /** method to check if items are equal. */

  MethodFunc free_key;

  MethodFunc free_value;

};

/* -------------------------------

 * The SMapItem functions.

 * -------------------------------

 */

/** @breif

 * create a new SMapItem.

 *

 * @param key The key to be added to the item.

 * @param value The value to be added to the item.

 * @param free_key The function to be used to free the key.

 * @param free_value The function to be used to free the value.

 */

SMapItem * s_map_item_new (void * key, void * value);

/** @breif

 * Frees a SMapItem.

 * 

 * @param self the item to be freed.

 * @param free_key The function to be used to free the key.

 * @param free_value The function to be used to free the value.

 */

void s_map_item_free (SMapItem * self, MethodFunc free_key,

                                       MethodFunc free_value);

/* -------------------------------

 * The SMap functions.

 * -------------------------------

 */

/** @brief

 * s_map_new creates a new SMap object, it takes a CompFunc as an argument.

 *

 * @param comp_func tells the SMap object if the key already exists when

 * adding key/value pares or when searching after a key when retrieving a value.

 *

 * The @c CompFunc returns true if the first and second parameters are equal,

 * otherwise false.

 *

 * @todo

 * Check if free_key and/or free_value is null and set them to something

 * appropriate.

 */

SMap * s_map_new ( CompFunc comp_func, MethodFunc free_key,

                                       MethodFunc free_value);

/** @breif

 * This function frees an instance of an SMap.

 * 

 * @param self the object to free.

 */

void s_map_free (SMap * self);

/** @breif

 * This function adds a key/value pair to an SMap.

 * 

 * @param self the SMap to add the key/value pair to.

 * @param key the key that is used to

 *

 * @todo

 *  make it return false on failure, or some other nastiness.

 */

void s_map_add (SMap * self ,void * key, void * value);

/** @breif

 * Get a value using using a key.

 * 

 * @param self the SMap that you want to retrieve a value from.

 * @param key the key that you use to retrieve the value from the SMap from

 *            with.

 */

void * s_map_get (SMap * self, void * key);

/**

 * @todo

 */

void  s_map_remove (SMap * self, void * key);

#endif