/*
 * (c) Copyright, Real-Time Innovations, 2002-2026.
 * All rights reserved.
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */

#ifndef reda_hash_h
#define reda_hash_h

#include "reda/reda_dll.h"

#ifdef __cplusplus
extern "C" {
#endif

/* Doxygen file & module documentation ==================================*/
/*e \file
 *    \brief Defines a hashing capability
 */

/*e \defgroup REDAHashClass REDAHash
 * \ingroup REDAModule
 *
 * @brief hashing prototypes and built-in hash functions.
 *
 * They are used when creating a \ref REDATable either directly or through
 * the \ref REDADatabase.
 */

/*e \ingroup REDAHashClass
 *  @brief The prototype of a hash function.  Such a function takes a key and
 *  returns a number between 0 and numberOfBuckets-1.
 */
typedef int (*REDAHashFunction)(const void *key, int numberOfBuckets);

/*e \ingroup REDAHashClass
 *  @brief This structure consists of a hash-function and the number of buckets.
 *
 *  NumerOfBuckets must be larger or equal to 1.  The hash-function
 *  must return an int between 0 and the numberOfBuckets-1.
 */
struct REDAHashDefinition {
    /*e Hash function. Must reutrn a int between 0 and the numberOfBuckets-1.
     */
    REDAHashFunction hashFunction;
    /*e number of buckets. Must be larger or equal to 1. */
    int numberOfBuckets;
};

/*e  \ingroup REDAHashClass
 *
 * @brief Hashes a keys interpreted as pointers to int[1].
 *
 *  This function is suitable to be used as a
 *  hash function when the keys are of type int[1] or
 *  can be hashed as if they where of such type.
 *
 *  @param key \In. The key to hash interpeted as an int*. Can't be NULL.
 *
 *  @param numBuckets \In. The number of buckets.  The function needs
 *         to return an int between 0 and numBuckets-1
 *
 *  @returns a hash of the key
 *
 * @exception none
 *
 * @mtsafety safe provided that key is not modified concurrently.
 */
extern REDADllExport int REDAHash_hashSimpleInt(
        const void *key,
        int numBuckets);

/*e  \ingroup REDAHashClass
 *
 *  @brief Hashes a keys interpreted as pointers to int[2].
 *
 *   This function is suitable to be used as a
 *   hash function when the keys are of type int[2] or
 *   can be hashed as if they where of such type.
 *
 *   @param key \In. The key to hash interpeted as an int[2]. Can't be NULL.
 *
 *   @param numBuckets \In. The number of buckets.  The function needs
 *          to return an int between 0 and numBuckets-1
 *
 *   @returns a hash of the key
 *
 *  @exception none
 *
 *  @mtsafety safe provided that key is not modified concurrently.
 */
extern REDADllExport int REDAHash_hashSimpleDoubleInt(
        const void *key,
        int numBuckets);

/*e  \ingroup REDAHashClass
 *
 *@brief Hashes a key interpreted as pointers to int[3].
 *
 * This function is suitable to be used as a
 * hash function when the keys are of type int[3] or
 * can be hashed as if they where of such type.
 *
 * @param key \In. The key to hash interpeted as an int[3]. Can't be NULL.
 *
 * @param numBuckets \In. The number of buckets.  The function needs
 *        to return an int between 0 and numBuckets-1
 *
 * @returns a hash of the key
 *
 *@exception none
 *
 *@mtsafety safe provided that key is not modified concurrently.
 */
extern REDADllExport int REDAHash_hashSimpleTripleInt(
        const void *key,
        int numBuckets);

/*e  \ingroup REDAHashClass
 *
 *  @brief Hashes a key interpreted as pointers to int[4].
 *
 *   This function is suitable to be used as a
 *   hash function when the keys are of type int[4] or
 *   can be hashed as if they where of such type.
 *
 *   @param key \In. The key to hash interpeted as an int[4]. Can't be NULL.
 *
 *   @param numBuckets \In. The number of buckets.  The function needs
 *          to return an int between 0 and numBuckets-1
 *
 *   @returns a hash of the key
 *
 *  @exception none
 *
 *  @mtsafety safe provided that key is not modified concurrently.
 */
extern REDADllExport int REDAHash_hashSimpleQuadInt(
        const void *key,
        int numBuckets);

/*e  \ingroup REDAHashClass
 *
 * @brief Hashes a key interpreted as pointers to int[5].
 *
 *  This function is suitable to be used as a
 *  hash function when the keys are of type int[5] or
 *  can be hashed as if they where of such type.
 *
 *  @param key \In. The key to hash interpeted as an int[5]. Can't be NULL.
 *
 *  @param numBuckets \In. The number of buckets.  The function needs
 *         to return an int between 0 and numBuckets-1
 *
 *  @returns a hash of the key
 *
 * @exception none
 *
 * @mtsafety safe provided that key is not modified concurrently.
 */
extern REDADllExport int REDAHash_hashSimpleFiveInt(
        const void *key,
        int numBuckets);

/*e  \ingroup REDAHashClass
 *
 * @brief Hashes a REDAWeakReference key.
 *
 * @param key \In. The key to hash interpeted as REDAWeakReference. Can't be
 * NULL.
 *
 * @param numBuckets \In. The number of buckets.  The function needs
 * to return an int between 0 and numBuckets-1
 *
 * @returns a hash of the key
 *
 * @exception none
 *
 * @mtsafety safe provided that key is not modified concurrently.
 */
extern REDADllExport int REDAHash_hashWeakReference(
        const void *key,
        int numBuckets);

/*e \ingroup REDAHashClass
 *
 * @brief Compute the hash function on a key given a definition of the hash.
 *
 * @pre hashDefinition is a valid definition (valid function pointer
 *      and numberOfBuckets >= 1) and the passed key is of the type
 *      that the hashFunction expects
 *
 * @post none
 *
 * @return the value of the hash
 *
 * @exception none
 *
 * @mtsafety safe provided that key is not modified concurrently.
 */
int REDAHash_computeHash(
        struct REDAHashDefinition *hashDefinition,
        const void *key);

#ifdef __cplusplus
} /* extern "C" */
#endif

/* performance boosting macros and optimizations */
#include "reda/reda_hash_impl.h"

#endif /* reda_hash_h */