/*! Sunrise Data Dictionary Library
 *
 *  @brief a library for hashtable storage of arbitrary data objects
 *  with built-in reference counting and guaranteed order iteration.
 *
 *  @file dd_hash_functions.h
 *  built-in hash functions
 *
 *  @author Benjamin Kowarsch <nospam://com.sunrise-tel/~firstname~>
 *
 *  @note The author's true email address is herewith specifically excluded
 *  from the license of this software.  You are _not permitted_ to make the
 *  author's true email address available to any third party.  You may only
 *  pass on the modified version of the email address as presented above.
 *
 * (C) 2006 Sunrise Telephone Systems Ltd. All rights reserved.
 *
 * @cond LICENSE_TERMS
 *
 * Permission is  hereby granted,  free of charge,  to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction,  including without limitation
 * the rights  to  use, copy, modify, merge, publish, distribute, sublicense,
 * and/or  sell copies of  the Software,  and  to permit persons  to whom the
 * Software is furnished to do so,  subject to the following conditions:
 *
 * The above copyright notice  and  this permission notice  shall be included
 * in all copies or substantial portions of the Software.
 *
 * Under no circumstances is it permitted for any licensee to take credit for
 * the creation of  the Software,  to claim  authorship  or  ownership in the
 * Software  or in any other way  give the impression  that they have created
 * the Software.  Credit to the  true authors  and  copyright holders  of the
 * Software is absolutely mandatory and must be given as follows:
 *
 * Software packages incorporating the Software or substantial portions of it
 * shall display  a copyright notice  for the Software  in the same manner as
 * they  display  any  other copyright notice;  shall  display  an authorship
 * notice  for  the Software  in the  same manner  as they display  any other
 * authorship notice;  and shall display  the license terms or a reference to
 * the license terms of the Software  in the same manner  as they display any
 * other license or license reference.
 *
 * GUI-based or GUI-alike  interactive installers  installing the Software or
 * substantial portions of it, shall display the Software's copyright notice,
 * authorship notice  and  license terms  in  full  during  the  installation
 * process.  Other installers such as shell command driven package installers
 * on Unix systems shall display copyright,  authorship  and  license  in the
 * same  manner  as for  any other software.  Installers shall allow users to
 * install the license file for the Software along with the Software itself.
 *
 * Software  which makes use of  but  does not incorporate,  nor bundle,  nor
 * install the Software  or substantial portions of it,  is  NOT  required to
 * display any copyright, authorship, license terms  or license reference for
 * the Software.  Static linking to the Software constitutes 'incorporating',
 * dynamic linking to the Software constitutes 'making use of' the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED,  INCLUDING  BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE  AND  NONINFRINGEMENT.  IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY,  WHETHER IN AN ACTION OF CONTRACT,  TORT OR OTHERWISE,  ARISING
 * FROM,  OUT OF  OR  IN CONNECTION WITH THE SOFTWARE  OR  THE USE  OR  OTHER
 * DEALINGS IN THE SOFTWARE.
 *
 * In countries and territories  where  the  above  no-warranty disclaimer is
 * not permissible by applicable law, the following terms apply:
 *
 * NO PERMISSION TO USE THE SOFTWARE IS GRANTED  AND THE SOFTWARE MUST NOT BE
 * USED AT ALL  IN SUCH COUNTRIES AND TERRITORIES WHERE THE ABOVE NO-WARRANTY
 * DISCLAIMER IS NOT PERMISSIBLE AND INVALIDATED BY APPLICABLE LAW.  HOWEVER,
 * THE COPYRIGHT HOLDERS HEREBY WAIVE THEIR RIGHT TO PURSUE OFFENDERS AS LONG
 * AS THEY OTHERWISE ABIDE BY THE TERMS OF THE LICENSE  AS APPLICABLE FOR USE
 * OF THE SOFTWARE  IN COUNTRIES AND TERRITORIES WHERE THE ABOVE  NO-WARRANTY
 * DISCLAIMER IS PERMITTED BY APPLICABLE LAW. THIS WAIVER DOES NOT CONSTITUTE
 * A LICENSE TO USE THE SOFTWARE IN COUNTRIES AND TERRITORIES WHERE THE ABOVE
 * NO-WARRANTY DISCLAIMER IS  NOT PERMISSIBLE  AND  INVALIDATED BY APPLICABLE
 * LAW.  ANY LIABILITY OF ANY KIND IS CATEGORICALLY RULED OUT AT ALL TIMES.
 *
 * @endcond
 */

#ifndef _DD_HASH_FUNCTIONS_H
#define _DD_HASH_FUNCTIONS_H

#include "dd_types.h"
#include "dd_macros.h"


// --------------------------------------------------------------------------
// Hash function type
// --------------------------------------------------------------------------
//
// Function pointer type for hash functions.

typedef cardinal (*dd_hash_function) (const char *);


// --------------------------------------------------------------------------
// function:  dd_SDBM_hash_string(string)
// --------------------------------------------------------------------------
//
// Returns the hash value of the null terminated C string <string>  using the
// SDBM hash algorithm.  The number  of significant characters  for which the
// hash  value  will  be  calculated  is limited to  the  value  returned  by
// function dd_significant_chars().
//
// Returns 0 if <string> is empty or NULL.

cardinal dd_SDBM_hash_string(const char *string) DD_PURE_FUNCTION;


// --------------------------------------------------------------------------
// function:  dd_SDBM_hash_string_toupper(string)
// --------------------------------------------------------------------------
//
// Returns the hash value of the null terminated C string <string>  using the
// SDBM hash algorithm after converting <string> to its uppercase equivalent,
// which  effectively makes the function  case insensitive.   Case conversion
// is limited  to characters  in the ASCII range 'a' to 'z'.  The  number  of
// significant characters  for which  the hash value  will  be  calculated is
// limited to the value returned by function dd_significant_chars().
//
// Returns 0 if <string> is empty or NULL.

cardinal dd_SDBM_hash_string_toupper(const char *string) DD_PURE_FUNCTION;	


// --------------------------------------------------------------------------
// Function:  dd_DJB_hash_string(string)
// --------------------------------------------------------------------------
//
// Returns the hash value of the null terminated C string <string>  using the
// DJB hash algorithm  (published by D.J.Bernstein on Usenet in comp.lang.c).
// The number  of  significant characters  for which the  hash value  will be
// calculated    is    limited   to   the   value   returned   by    function
// dd_significant_chars().
//
// Returns 0 if <string> is empty or NULL.

cardinal dd_DJB_hash_string(const char *string) DD_PURE_FUNCTION;


// --------------------------------------------------------------------------
// Function:  dd_DJB_hash_string_toupper(string)
// --------------------------------------------------------------------------
//
// Returns the hash value of the null terminated C string <string>  using the
// DJB hash algorithm after converting <string> to its  uppercase equivalent,
// which effectively makes the function case insensitive.  Case conversion is
// limited  to  characters  in  the  ASCII range 'A' to 'Z'.   The  number of
// significant characters  for which the  hash value  will be  calculated  is
// limited to the value returned by function dd_significant_chars().
//
// Returns 0 if <string> is empty or NULL.

cardinal dd_DJB_hash_string_toupper(const char *string) DD_PURE_FUNCTION;
	

// --------------------------------------------------------------------------
// Function:  dd_ELF_hash_string(string)
// --------------------------------------------------------------------------
//
// Returns the hash value of the null terminated C string <string>  using the
// ELF hash algorithm  (as used in most Unix systems for passwd hashes).  The
// number   of  significant characters  for  which  the  hash value  will  be
// calculated    is    limited   to   the   value   returned   by    function
// dd_significant_chars().
//
// Returns 0 if <string> is empty or NULL.

cardinal dd_ELF_hash_string(const char *string) DD_PURE_FUNCTION;


// --------------------------------------------------------------------------
// Function:  dd_ELF_hash_string_toupper(string)
// --------------------------------------------------------------------------
//
// Returns the hash value of the null terminated C string <string>  using the
// ELF hash algorithm after converting <string> to its  uppercase equivalent,
// which effectively makes the function case insensitive.  Case conversion is
// limited  to  characters  in  the  ASCII range 'A' to 'Z'.   The  number of
// significant characters  for which the  hash value  will be  calculated  is
// limited to the value returned by function dd_significant_chars().
//
// Returns 0 if <string> is empty or NULL.

cardinal dd_ELF_hash_string_toupper(const char *string) DD_PURE_FUNCTION;


// --------------------------------------------------------------------------
// Function:  dd_FNVM_hash_string(string)
// --------------------------------------------------------------------------
//
// Returns the hash value of the null terminated C string <string>  using the
// FNVM hash algorithm  (Fowler, Noll and Vo hash,  modified by Bret Mulvey).
// The number of  significant characters  for  which the hash value  will  be
// calculated   is   limited   to   the   value    returned    by    function
// dd_significant_chars().
//
// Returns 0 if <string> is empty or NULL.

cardinal dd_FNVM_hash_string(const char *string) DD_PURE_FUNCTION;


// --------------------------------------------------------------------------
// Function:  dd_FNVM_hash_string_toupper(string)
// --------------------------------------------------------------------------
//
// Returns the hash value of the null terminated C string <string>  using the
// FNVM  hash  algorithm   after  converting  <string>   to   its   uppercase
// equivalent,  which  effectively makes the hash function  case insensitive.
// Case conversion is  limited to characters  in the ASCII range  'A' to 'Z'.
// The number of  significant characters  for which  the hash value  will  be
// calculated   is   limited    to   the   value    returned    by   function
// dd_significant_chars().
//
// Returns 0 if <string> is empty or NULL.

cardinal dd_FNVM_hash_string_toupper(const char *string) DD_PURE_FUNCTION;


// --------------------------------------------------------------------------
// Function:  dd_HSIEH_hash_string(string)
// --------------------------------------------------------------------------
//
// Returns the hash value of the null terminated C string <string>  using the
// HSIEH hash algorithm (developed by Paul Hsieh).  The number of significant
// characters for which the hash value will be calculated  is limited  to the
// value returned by function dd_significant_chars().
//
// Returns 0 if <string> is empty or NULL.

cardinal dd_HSIEH_hash_string(const char *string) DD_PURE_FUNCTION;


// --------------------------------------------------------------------------
// Function:  dd_HSIEH_hash_string_toupper(string)
// --------------------------------------------------------------------------
//
// Returns the hash value of the null terminated C string <string>  using the
// HSIEH hash algorithm after converting <string> to its uppercase equivalent
// which  effectively  makes  the  hash  function   case  insensitive.   Case
// conversion is  limited to characters  in the ASCII range  'A' to 'Z'.  The
// The number of  significant characters  for which  the hash value  will  be
// calculated   is   limited    to   the   value    returned    by   function
// dd_significant_chars().
//
// Returns 0 if <string> is empty or NULL.

cardinal dd_HSIEH_hash_string_toupper(const char *string) DD_PURE_FUNCTION;


#endif

// END OF FILE