vector/itemkeyfun.h

   1 #ifndef itemkeyfun_H
   2 #define itemkeyfun_H
   3
   4 /**
   5  * \struct itemkeyfun
   6  *
   7  * itemkeyfun provides a meta-level representation for abstracting
   8  * items as pairs of keys and payload, and having a hashcode mapping
   9  * for keys. The key part is used for identifying items under the idea
  10  * that all items that have the same key are the same; distinct
  11  * representations of the same abstract entity. The hashcode scrambles
  12  * the key part in a consistent way into an ideal table index for the
  13  * items that have that key. Different keys may yield the same
  14  * hashcode.
  15  */
  16 typedef struct {
  17
  18 #define SELF void *this
  19     /**
  20      * This callback function should return the hashcode of a key. The
  21      * hashcode is used for indexing into the backing vector for
  22      * finding the an item via its key. The same key must map
  23      * consistently to the same hashcode while the hashtable contains
  24      * an item with that key. Different keys map map to the same
  25      * hashcode, in which case the vector placement is made at the
  26      * first empty or hole slot following the hashcode index.
  27      */
  28     unsigned long (*hashcode)(SELF,void *key);
  29
  30     /**
  31      * This callback function should determine whether an item has a
  32      * given key or not.
  33      */
  34     int (*haskey)(SELF,void *item,void *key);
  35
  36     /**
  37      * This callback function should return a (possibly temporary) key
  38      * of an item. It can be anything (i.e., with or without internal
  39      * structure) as it is treated as an identifier that other
  40      * callbacks recognize. It is merely understood as a value in an
  41      * identity domain.
  42      */
  43     void *(*itemkey)(SELF,void *item);
  44
  45     /**
  46      * This callback function should handle a key obtained from the
  47      * itemkey callback function, e.g., reclaim temporary allocation.
  48      */
  49     void (*releasekey)(SELF,void *key);
  50
  51 #undef SELF
  52 } itemkeyfun;
  53
  54 #endif