vector/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 #define SELF void *this
  21     /**
  22      * This callback function should return the hashcode of a key. The
  23      * hashcode is used for indexing into the backing Vector for
  24      * finding the an item via its key. The same key must map
  25      * consistently to the same hashcode while the hashtable contains
  26      * an item with that key. Different keys map map to the same
  27      * hashcode, in which case the Vector placement is made at the
  28      * first empty or hole slot following the hashcode index.
  29      */
  30     unsigned long (*hashcode)(SELF,void *key);
  31
  32     /**
  33      * This callback function should determine whether an item has a
  34      * given key or not.
  35      */
  36     int (*haskey)(SELF,void *item,void *key);
  37
  38     /**
  39      * This callback function should return a (possibly temporary) key
  40      * of an item. It can be anything (i.e., with or without internal
  41      * structure) as it is treated as an identifier that other
  42      * callbacks recognize. It is merely understood as a value in an
  43      * identity domain.
  44      */
  45     void *(*itemkey)(SELF,void *item);
  46
  47     /**
  48      * This callback function should handle a key obtained from the
  49      * itemkey callback function, e.g., reclaim temporary allocation.
  50      */
  51     void (*releasekey)(SELF,void *key);
  52
  53     /**
  54      * This callback function writes a representation of an item into
  55      * a character buffer.
  56      */
  57     int (*tostring)(SELF,void *item,char *buffer,int limit);
  58
  59 #undef SELF
  60 } ItemKeyFun;
  61
  62 #endif