/** @file  psHash.h
 *  @brief Contains support for basic hashing functions.
 *  @ingroup HashTable
 *
 *  This file will hold the prototypes for defining a hash table with arbitrary
 *  data types, allocating/deallocating that has table, adding and removing
 *  data from that hash table, and listing all keys defined in the hash table.
 *
 *  @author Robert Lupton, Princeton University
 *  @author Robert DeSonia, MHPCC
 *  @author GLG, MHPCC
 *
 *  @version $Revision: 1.9 $ $Name: not supported by cvs2svn $
 *  @date $Date: 2005-06-08 23:40:45 $
 *
 *  Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
 */

#ifndef PS_HASH_H
#define PS_HASH_H

/** \addtogroup HashTable
 *  \{
 */

#include "psList.h"

/** A bucket that holds an item of data. */
typedef struct psHashBucket
{
    char *key;                         ///< The key for this item of data.
    psPtr data;                        ///< The data itself.
    struct psHashBucket* next;         ///< The list of other possible keys.
}
psHashBucket;

//typedef struct HashTable psHash; ///< Opaque type for a hash table

/** The hash-table itself. */
typedef struct psHash
{
    psS32 nbucket;                     ///< Number of buckets in hash table.
    psHashBucket* *buckets;            ///< The bucket data.
}
psHash;

/// Allocate hash buckets in table.
psHash* psHashAlloc(
    psS32 nbucket                  ///< The number of buckets to allocate.
);

/// Insert entry into table.
psBool psHashAdd(
    psHash* table,                 ///< The table to insert in.
    const char *key,               ///< The key to use.
    psPtr data                     ///< The data to insert.
);

/// Lookup key in table.
psPtr psHashLookup(
    psHash* table,                 ///< The table to lookup key in.
    const char *key                ///< The key to lookup.
);

/// Remove key from table.
psBool psHashRemove(
    psHash* table,                 ///< The table to lookup key in.
    const char *key                ///< The key to lookup.
);

/// List all keys in table.
psList* psHashKeyList(
    psHash* table                  ///< The table to list keys from..
);

/** Create a psArray from a psHash contents.
 *
 *  @return psArray*       A new psArray with duplicate contents of the input psHash
 */
psArray* psHashToArray(
    psHash* table                  ///< The table to convert to psArray.
);

/* \} */// End of DataGroup Functions

#endif // #ifndef PS_HASH_H
