/**
 * @file hashMap.h
 * @ingroup collection
 *
 * Hashmap module.
 *
 * @author Geoff Davis <geoff@circlemudsquared.org>
 *
 * @par Copyright:
 *   Copyright (C) 2006 Geoff Davis <geoff@circlemudsquared.org><br>
 *                      Greg Buxton <greg@circlemudsquared.org>
 *
 * @par
 *   Copyright (C) 1993, 94 by the Trustees of the Johns Hopkins University<br>
 *   CircleMUD is based on DikuMUD, Copyright (C) 1990, 1991.
 *
 * @par
 *   All rights reserved.  See license.doc for complete information.
 *
 * @package cs
 * @version 1.0
 */

#ifndef __HASHMAP_H__
#define __HASHMAP_H__

#include "base.h"

/**
 * An alias for struct _hashMap_t.
 * @typedef struct _hashMap_t
 */
typedef struct _hashMap_t hashMap_t;

/**
 * An alias for struct _hashMapEntry_t.
 * @typedef struct _hashMapEntry_t
 */
typedef struct _hashMapEntry_t hashMapEntry_t;

/**
 * An alias for struct _hashMapIterator_t.
 * @typedef struct _hashMapIterator_t
 */
typedef struct _hashMapIterator_t hashMapIterator_t;

/**
 * The type of a hash key.
 * @typedef unsigned long
 */
typedef unsigned long hashKey_t;

/**
 * The type of a hash function. Functions of this type are used to create
 * a hash code, also known as a hash key, for a given user-provided key.
 * @typedef hashKey_t (*)(const void*)
 */
typedef hashKey_t (*hashFunction_t)(const void *key);

/**
 * The hash map structure.
 * @{
 */
struct _hashMap_t {
  hashMapEntry_t **entryTable;          /**< the vector of hash entry lists.*/
  size_t           entryTableSize;      /**< the size of the entry table.   */
  hashFunction_t   keyHashFunction;     /**< the function to hash map keys. */
  freeFunction_t   keyFreeFunction;     /**< the free function for keys.    */
  size_t           size;                /**< the number of entries (elements)*/
  freeFunction_t   valueFreeFunction;   /**< the free function for values.  */
};
/** @} */

/**
 * The hashmap entry structure.
 * @{
 */
struct _hashMapEntry_t {
  hashKey_t        hashKey;             /**< the hash key for the key.      */
  void            *key;                 /**< the key of the entry.          */
  hashMapEntry_t  *nextEntry;           /**< the next entry in the hash list*/
  void            *value;               /**< the value of the entry.        */
};
/** @} */

/**
 * The hashmap iterator structure.
 * @{
 */
struct _hashMapIterator_t {
  hashMap_t       *hashMap;             /**< the hashmap being iterated.    */
  hashMapEntry_t  *lastReturned;        /**< the last entry returned.       */
  hashMapEntry_t  *nextEntry;           /**< the next entry to be returned. */
  size_t           nextEntryIndex;      /**< the index of current hash list.*/
};
/** @} */

/*
 * hashmap functions
 */

/**
 * Removes all elements from a hashmap.
 * @param hashMap the hashmap to be cleared
 * @return none
 */
void hashMap_clear(hashMap_t *hashMap);

/**
 * Returns whether a hashmap contains a particular key.
 * @param hashMap the hashmap whose contents are to be tested
 * @param key the key for which to test
 * @return true if the hashmap contains a matching key;
 *         false otherwise
 */
bool hashMap_containsKey(hashMap_t *hashMap, const void *key);

/**
 * Constructs a new hashmap.
 * @param entryTableSize the initial size of the hashmap entry table
 * @param hashFunction the hash function to be used to hash keys
 * @param keyFreeFunction the free function to be called for map keys
 * @param valueFreeFunction the free function to be called for map values
 * @return a new hashmap, or NULL
 */
hashMap_t *hashMap_create(size_t entryTableSize, hashFunction_t hashFunction,
  freeFunction_t keyFreeFunction, freeFunction_t valueFreeFunction);

/**
 * Deletes a mapping from a hashmap.
 * @param hashMap the hashmap from which to remove a mapping
 * @param key the key of the mapping to be removed
 * @return true if the size of the hashmap was changed by this function;
 *         false otherwise
 */
bool hashMap_delete(hashMap_t *hashMap, const void *key);

/**
 * Frees a hashmap.
 * @param hashMap the hashmap to be freed
 * @return none
 */
void hashMap_free(hashMap_t *hashMap);

/**
 * Returns the size of a hashmap.
 * @param hashMap the hashmap to be tested
 * @return the size of the hashmap, or zero (0)
 */
size_t hashMap_getSize(hashMap_t *hashMap);

/**
 * Returns the value for a given key.
 * @param hashMap the hashmap to be searched
 * @param key the key for which to retreive a value
 * @param defaultValue the value to be retuned if the key cannot be not found
 * @return the value associated with the key, the default value, or NULL
 */
void *hashMap_getValue(hashMap_t *hashMap, const void *key,
  void *defaultValue);

/**
 * Returns whether a hashmap is empty.
 * @param hashMap the hashmap to be tested
 * @return true if the hashmap is empty, having a size of zero (0);
 *         false otherwise
 */
bool hashMap_isEmpty(hashMap_t *hashMap);

/**
 * Inserts a key-to-value mapping into a hashmap.
 * @param hashMap the hashmap into which a mapping is to be inserted
 * @param key the key to be inserted
 * @param value the value to be inserted
 * @return true if the size of the hashmap was modified by this function;
 *         false otherwise
 */
bool hashMap_insert(hashMap_t *hashMap, void *key, void *value);

/*
 * hashmap iterator functions
 */

/**
 * @example hashMapIterator_example.c    L
 * Example of hashMapIterator implementation
 */  

/**
 * Constructs a new hashmap iterator.
 * @param hashMap the hashmap to be iterated
 * @return a new hashmap iterator, or NULL
 */
hashMapIterator_t *hashMapIterator_create(hashMap_t *hashMap);

/**
 * Frees a hashmap iterator.
 * @param iter the hashmap iterator to be freed
 * @return none
 */
void hashMapIterator_free(hashMapIterator_t *iter);

/**
 * Returns whether a hashmap iterator has more mappings.
 * @param iter the hashmap iterator to be tested
 * @return true if there are more mappings to be iterated;
 *         false otherwise
 */
bool hashMapIterator_hasNext(hashMapIterator_t *iter);

/**
 * Returns the key of the next mapping in the underlying hashmap and
 * advances the hashmap iterator.
 * @param iter the hashmap iterator to be advanced
 * @return the next key in the hashmap, or NULL
 */
void *hashMapIterator_nextKey(hashMapIterator_t *iter);

/**
 * Returns the value of the next mapping in the underlying hashmap and
 * advances the hashmap iterator.
 * @param iter the hashmap iterator to be advanced
 * @return the next value in the hashmap, or NULL
 */
void *hashMapIterator_nextValue(hashMapIterator_t *iter);

/**
 * Removes the last element returned by a hashmap iterator.
 * @param iter the hashmap iterator from which to remove an element
 * @return none
 */
void hashMapIterator_remove(hashMapIterator_t *iter);

/*
 * private hashmap functions
 */

/**
 * Removes a hashmap entry from a hashmap and updates the hashmap size
 * using a pair of free functions.
 * @param hashMap the hashmap whose entry is to be unlinked
 * @param entry the entry to be removed
 * @param freeKeyFunction the free function to be called for each key
 * @param freeValueFunction the free function to be called for each value
 * @return none
 */                                      
void hashMapPrivate_deleteEntry(hashMap_t *hashMap, hashMapEntry_t *entry);

/**
 * Returns the hashmap entry corresponding to a particular key.
 * @param hashMap the hashmap whose entry is to be retrieved
 * @return the matching hashmap entry, or NULL
 */
hashMapEntry_t *hashMapPrivate_getEntry(hashMap_t *hashMap, const void *key);

void hashMapIterator_next(hashMapIterator_t *iter);
void *hashMapIterator_getValue(hashMapIterator_t *iter);

#endif /* __HASHMAP_H__ */