
/** @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 George Gusciora, MHPCC
 *  @author Robert DeSonia, MHPCC
 *
 *  @version $Revision: 1.7 $ $Name: not supported by cvs2svn $
 *  @date $Date: 2005-02-17 19:26:23 $
 *
 *  Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
 */
#if !defined(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;                         ///< key for this item of data
    psPtr data;                        ///< the data itself
    struct psHashBucket* next;         ///< 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,                 ///< table to insert in
    const char *key,               ///< key to use
    psPtr data                     ///< data to insert
);

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

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

/// List all keys in table.
psList* psHashKeyList(
    psHash* table                  ///< 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                  ///< table to convert to psArray
);

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

#endif
