GAT Documentation

00001 /** @file GATTableAnyKey.h
00002  *  Header file for the GATTableAnyKey class.
00003  *
00004  *  This in an additional interface to the GATTable object, which allows to 
00005  *  specify arbitrary key types.
00006  *
00007  *  Please note, that table type of tables are not serialisable! 
00008  *  So use it with care.
00009  *
00010  *  @date Tue Nov 4 2003
00011  *
00012  *  @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATTableAnyKey.h,v 1.5 2004/03/24 19:30:58 hartmutkaiser Exp $
00013  *
00014  *  Copyright (C) Hartmut Kaiser
00015  *  This file is part of the GAT Engine.
00016  *  Contributed by Hartmut Kaiser <hartmutkaiser [at] t-online [dot] de>.
00017  *
00018  *  Use, modification and distribution is subject to the Gridlab Software
00019  *  License. (See accompanying file GLlicense.txt or copy at
00020  *  http://www.gridlab.org/GLlicense.txt)
00021  */
00022  
00023 #ifndef _GATTABLEANYKEY_H_
00024 #define _GATTABLEANYKEY_H_ 1
00025 
00026 #include "GAT.h"
00027 
00028 /* Callback function prototypes for GATTable genericity */
00029 typedef GATuint32 (* GATTable_GetKeySizeProc)(GATTable_const, void const *);
00030 typedef GATBool (* GATTable_EqualKeysProc)(GATTable_const, void const *, 
00031   void const *);
00032 typedef unsigned long (* GATTable_GetHashProc)(GATTable_const, void const *);
00033 typedef int (* GATTable_CloneKeyProc)(GATTable_const, void const *, void **);
00034 typedef void (* GATTable_DestroyKeyProc)(GATTable_const, void **);
00035 
00036 #ifdef __cplusplus
00037 extern "C" {
00038 #endif
00039 
00040 /** GATTable_Default_Equal_Keys
00041  *
00042  *  The function GATTable_Default_Equal_Keys is the default callback function 
00043  *  which is used to compare two different keys of a GATTableAnyKey for 
00044  *  equality.
00045  *  This function compares the keys with the help of the function memcmp.
00046  *
00047  *  @param table The table, for which these keys are to be used.
00048  *  @param key1 first key for comparison.
00049  *  @param key2 second key for comparison.
00050  *
00051  *  @return GATTrue for equal keys, GATFalse for non equal keys
00052  */
00053 GATBool 
00054   GATTable_Default_Equal_Keys(GATTable_const table, void const *key1, 
00055     const void *key2);
00056 
00057 /** GATTable_Default_Hash_sdbm
00058  *
00059  *  The function GATTable_Default_Hash_sdbm is the default callback function 
00060  *  which is used to calculate the hash value for a given key. 
00061  *  This function calculates the hash value based on the plain memory 
00062  *  representation of the key.
00063  *  
00064  *  @param table The table, for which this hash value is to be calculated.
00065  *  @param key The key to create a hash from.
00066  *
00067  *  @return the hash value
00068  */
00069 unsigned long 
00070   GATTable_Default_Hash_sdbm(GATTable_const table, void const *key);
00071   
00072 /** GATTable_Default_CloneKey
00073  *
00074  *  The function GATTable_Default_CloneKey is the default callback function 
00075  *  which is used to copy a key to a new location. 
00076  *  This function calculates copies the key with the help of the function 
00077  *  memcpy.
00078  *  
00079  *  @param table The table, into which this key is to be inserted.
00080  *  @param src The source memory area, where the key is to be copied from.
00081  *  @param dest The destination area, which receives the new key. 
00082  *
00083  *  @return A GAT error code.
00084  */
00085 GATResult
00086   GATTable_Default_Clone_Key(GATTable_const table, void const *src, 
00087     void **dest);
00088   
00089 /** GATTable_Default_Destroy_Key
00090  *
00091  *  The function GATTable_Default_Destroy_Key is the default callback function 
00092  *  which is used to destroy a key (deallocate all associated memory).
00093  *  This function compares free's the key with the std function free().
00094  *
00095  *  @param table The table, for which these keys are to be used.
00096  *  @param key The pointer to the key to deallocate.
00097  */
00098 void 
00099   GATTable_Default_Destroy_Key(GATTable_const table, void **key);
00100 
00101 /** GATTable_CreateAnyKey
00102  *  @brief Create the GATTable object.
00103  *
00104  *  This is the method used by any application code to create a GATTable
00105  *  object, which used the provided callback functions.
00106  *
00107  *  Note though, that objects of this type may not be used for serialisation.
00108  *  
00109  *  @param get_keysize The callback function to calculate the size of a given 
00110  *        key. This parameter must be supplied.
00111  *  @param equalkeys The callback function to compare two keys for equality. If
00112  *        this param is 0 (zero) the default callback function will be used
00113  *        (GATTable_Default_Equal_Keys).
00114  *  @param get_hash The callback function to calculate the hash value for a 
00115  *        given key. If this param is 0 (zero) the default callback function 
00116  *        will be used used (GATTable_Default_Hash_sdbm).
00117  *
00118  *  @return The GATTable object
00119  */
00120 GATTable GATTable_CreateAnyKey(GATTable_GetKeySizeProc get_keysize, 
00121   GATTable_EqualKeysProc equalkeys, GATTable_CloneKeyProc copykey, 
00122   GATTable_GetHashProc get_hash, GATTable_DestroyKeyProc destroy_key);
00123 
00124 #ifdef __cplusplus
00125 }
00126 #endif
00127 
00128 #endif /* _GATTABLEANYKEY_H_ */