typing/ItemKeyFun.h

   1 #ifndef ItemKeyFun_H
   2 #define ItemKeyFun_H
   3
   4 #include <stdio.h>
   5
   6 /**
   7  * \struct ItemKeyFun
   8  *
   9  * ItemKeyFun provides a meta-level representation for abstracting
  10  * items as pairs of keys and payload, and having a hashcode mapping
  11  * for keys. The key part is used for identifying items under the idea
  12  * that all items that have the same key are the same; distinct
  13  * representations of the same abstract entity. The hashcode scrambles
  14  * the key part in a consistent way into an ideal table index for the
  15  * items that have that key. Different keys may yield the same
  16  * hashcode.
  17  */
  18 typedef struct {
  19
  20     /**
  21      * This callback function should return the hashcode of a key. The
  22      * hashcode is used for indexing into the backing Vector for
  23      * finding the an item via its key. The same key must map
  24      * consistently to the same hashcode while the hashtable contains
  25      * an item with that key. Different keys map map to the same
  26      * hashcode, in which case the Vector placement is made at the
  27      * first empty or hole slot following the hashcode index.
  28      */
  29     unsigned long (*hashcode)(void *this,void *key);
  30
  31     /**
  32      * This callback function should determine whether an item has a
  33      * given key or not.
  34      */
  35     int (*haskey)(void *this,void *item,void *key);
  36
  37     /**
  38      * This callback function should return a (possibly temporary) key
  39      * of an item. It can be anything (i.e., with or without internal
  40      * structure) as it is treated as an identifier that other
  41      * callbacks recognize. It is merely understood as a value in an
  42      * identity domain.
  43      */
  44     void *(*itemkey)(void *this,void *item);
  45
  46     /**
  47      * This callback function should handle a key obtained from the
  48      * itemkey callback function, e.g., reclaim temporary allocation.
  49      */
  50     void (*releasekey)(void *this,void *key);
  51
  52     /**
  53      * This callback function writes a representation of an item into
  54      * a character buffer.
  55      */
  56     int (*tostring)(void *this,void *item,char *buffer,int limit);
  57
  58 } ItemKeyFun;
  59
  60 /**
  61  * \brief Trampoline function for the ItemKeyFun.hashcode callback.
  62  *
  63  * The default is to use the pointer itself.
  64  */
  65 extern unsigned long ItemKeyFun_hashcode(void *this,void *key);
  66
  67 /**
  68  * \brief Trampoline function for the ItemKeyFun.haskey callback.
  69  */
  70 extern int ItemKeyFun_haskey(void *this,void *item,void *key);
  71
  72 /**
  73  * \brief Trampoline function for the ItemKeyFun.itemkey callback.
  74  */
  75 extern void *ItemKeyFun_itemkey(void *this,void *item);
  76
  77 /**
  78  * \brief Trampoline function for the ItemKeyFun.releasekey callback.
  79  */
  80 extern void ItemKeyFun_releasekey(void *this,void *key);
  81
  82 /**
  83  * \brief Trampoline function for the ItemKeyFun.tostring callback.
  84  */
  85 extern int ItemKeyFun_tostring(void *this,void *item,char *buffer,int limit);
  86
  87 #endif