HASH(3pub)

💖 HASH(3pub) 💖

okay bestie, welcome to the C Programmer's Manual and specifically to HASH(3pub) — the pub lib's generic hash tables, and yes they ate 🫶

---

✨ NAME ✨

hash_create, hash_destroy, hash_install, hash_lookup, hash_uninstall, hash_iter — generic hash tables. that's it that's the whole vibe 🌸

---

✨ SYNOPSIS ✨

#include <publib.h>

Hashtab *hash_create(unsigned long (*fun)(void *),
         int (*cmp)(const void *, const void *));
void hash_destroy(Hashtab *ht);
void *hash_install(Hashtab *ht, void *data, size_t size);
void *hash_lookup(Hashtab *ht, void *data);
int hash_uninstall(Hashtab *ht, void *data);
int hash_iter(Hashtab *ht, int (*doit)(void *, void *), void *param);

like look at those signatures, they're giving function pointer energy 💅

---

✨ DESCRIPTION ✨

so these functions implement generic hash tables, no cap. the table gets created by hash_create and destroyed by hash_destroy. that's the lifecycle, that's the circle of life 🦋

the fun argument is a pointer to the hashing function, and it must convert a datum to an unsigned long, which then gets converted into an index into the hashing table. that's the whole pipeline bestie.

cmp is a qsort(3)-like comparison function, used to compare to (wannabe) hash table elements. yes they really said "wannabe" 😭 iconic honestly.

---

🎀 hash_install

installs a new datum into the table. you hand it a pointer to the data and the size of the data as the arguments.

• if the size is 0, only the pointer value gets copied to the table. just the pointer, nothing else, keep it light ✨
• otherwise, a copy of the data is made into dynamically allocated memory. so it's actually yours now 🫶

---

🎀 hash_lookup

tries to find a datum in the hash table. you give it a pointer to another datum as the argument. the comparison function should compare equal (return 0) the desired datum and this datum — but lowkey the argument needn't be a fully initialized datum, although that is up to the writer of the comparison function. so like, it's a vibe, but it's their vibe 😌

there cannot be two elements in the hash table that are equal (the comparison function returns 0 for them). and it is up to the user to handle collisions. that's on you bestie, not on us 💀

---

🎀 hash_uninstall

removes an element from a table. the argument is a pointer to a datum that identifies the element. bye babe 👋

---

🎀 hash_iter

goes through every element in the hash table and calls the doit function for each one.

• the first argument it provides to doit is the element in question
• the second is whatever was given to hash_iter as param

if doit returns -1 or 0 for any element in the hash table, hash_iter immediately returns without going through the remaining elements in the hash table. like it just leaves, mid-party, no goodbye 😭

any other return value from doit is ignored. ignored. not even acknowledged. 🙈

---

✨ RETURNS ✨

• hash_create returns a pointer to the new hash table, or NULL if it fails.
• hash_install returns a pointer to an element in the table — either the installed one, or one that was already installed, if one tries to install the same datum twice.
• hash_uninstall returns 0 if it found the element in the array, or -1 if it didn't.
• hash_lookup returns a pointer to the element it finds, or NULL if it doesn't find anything beautiful. 💔 (yes, that's the actual wording, and honestly? poetry.)
• hash_iter returns -1, 0, or 1. if hash_iter receives a return value of -1 or 0 for some element from doit, hash_iter immediately returns -1 or 0, respectively. in all other cases hash_iter returns 1.

---

✨ SEE ALSO ✨

• publib(3)
• qsort(3)
• bsearch(3)

go read those too bestie, they're all part of the family 🌈

---

✨ AUTHOR ✨

Lars Wirzenius (lars.wirzenius@helsinki.fi) — the icon, the legend, the moment 👑

---

okay and that's the whole page, we're done here 💜 this little gem came out of Publib's C Programmer's Manual, under the HASH(3pub) title, and it's been sitting there since forever. mwah, bye bestie 💅✨🎀