From: Ralph Ronnquist <ralph.ronnquist@gmail.com>
Date: Thu, 30 Jun 2022 11:52:19 +0000 (+1000)
Subject: separate hash function
X-Git-Tag: 0.1~1
X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=b37fca0c4e84edd8f63b1d8ce51d94e4c59b294e;p=rrq%2Frrqmisc.git

separate hash function
---

diff --git a/vector/itemkeyfun.h b/vector/itemkeyfun.h
new file mode 100644
index 0000000..ee71ca5
--- /dev/null
+++ b/vector/itemkeyfun.h
@@ -0,0 +1,54 @@
+#ifndef itemkeyfun_H
+#define itemkeyfun_H
+
+/**
+ * \struct itemkeyfun
+ *
+ * itemkeyfun provides a meta-level representation for abstracting
+ * items as pairs of keys and payload, and having a hashcode mapping
+ * for keys. The key part is used for identifying items under the idea
+ * that all items that have the same key are the same; distinct
+ * representations of the same abstract entity. The hashcode scrambles
+ * the key part in a consistent way into an ideal table index for the
+ * items that have that key. Different keys may yield the same
+ * hashcode.
+ */
+typedef struct _itemkeyfun {
+
+#define SELF struct _itemkeyfun *this
+    /**
+     * This callback function should return the hashcode of a key. The
+     * hashcode is used for indexing into the backing vector for
+     * finding the an item via its key. The same key must map
+     * consistently to the same hashcode while the hashtable contains
+     * an item with that key. Different keys map map to the same
+     * hashcode, in which case the vector placement is made at the
+     * first empty or hole slot following the hashcode index.
+     */
+    unsigned long (*hashcode)(SELF,void *key);
+
+    /**
+     * This callback function should determine whether an item has a
+     * given key or not.
+     */
+    int (*haskey)(SELF,void *item,void *key);
+
+    /**
+     * This callback function should return a (possibly temporary) key
+     * of an item. It can be anything (i.e., with or without internal
+     * structure) as it is treated as an identifier that other
+     * callbacks recognize. It is merely understood as a value in an
+     * identity domain.
+     */
+    void *(*itemkey)(SELF,void *item);
+
+    /**
+     * This callback function should handle a key obtained from the
+     * itemkey callback function, e.g., reclaim temporary allocation.
+     */
+    void (*releasekey)(SELF,void *key);
+
+#undef SELF
+} itemkeyfun;
+
+#endif