UHashTable(3U)

💖 UHashTable — hash table classes (from the InterViews Reference Manual, section 3U) 💖

okay bestie, sit down, hydrate, because today we're learning about UHashTable and UHashElem — two lil classes from <Unidraw/uhash.h> that are literally the backbone of storing stuff by key around here. no cap. 🦋

✨ SYNOPSIS ✨

#include <Unidraw/uhash.h>

🌸 DESCRIPTION 🌸

So UHashTable implements a simple open hash table. iconic behavior honestly. 💅

The number of slots is your call — you specify it when the table gets created. slay, customisation.

UHashTable stores UHashElem instances, and those little guys contain the key that gets hashed. so the key lives inside the element, got it?

Now here's the cute part: if you're writing code that uses UHashTables, you can derive from UHashElem to store extra data alongside the key. yes bestie, your own custom data. main character energy. 👑

UHashTable also gives you operations for iterating over the elements in the hash table, so you're never stuck staring at it from the outside. 🫶

🎀 UHASHELEM OPERATIONS 🎀

• UHashElem(void* = nil) — creates a UHashElem with the given key value. that's it, that's the constructor. 💖
• void* GetKey() / void SetKey(void*) — explicitly get and set the element's key value. no mystery, no drama, just getters and setters doing their thing. ✨

💜 UHASHTABLE PUBLIC OPERATIONS 💜

• UHashTable(int nslots) — creates a brand new UHashTable, and you tell it how many slots it's got. pick wisely bestie, that's the whole vibe. 🌈
• virtual void Register(void* key, UHashElem* = nil) — makes an entry into the hash table. 🔥 and here's the tea: if you don't hand it a UHashElem, this function calls the CreateElem function (described down below, keep scrolling) to make one for you, and then it calls SetKey on the result with key as the argument. it's giving "we got you covered". 💅
• virtual void Unregister(void* key) — removes the element with the matching key from the hash table and deletes it. gone. deleted. not just uninvited from the party, like, fully removed from existence. 💀
• void First(Iterator&)
• void Next(Iterator&)
• boolean Done(Iterator)
• UHashElem* GetElem(Iterator)

these four are your iteration squad — the operations for iterating over the elements in the hash table. ⭐

heads up: these operations do not guarantee a particular ordering for the iteration. so don't come for me when your elements show up in a different order than you imagined. it's giving chaos, but it's documented chaos. 😭

• First initializes an iterator to point to the first element in the traversal. 🥇
• Next increments the iterator to point to the following element. ➡️
• Done returns whether or not the iterator points beyond the last element in the traversal. 🛑
• GetElem returns the element that the given iterator is pointing at. 👀

• UHashElem* Find(void* key) — finds the element with the matching key in the hash table. and what counts as "matching"? that's defined by the Equal operation, described below. iykyk. 🔍

🧚 UHASHTABLE PROTECTED OPERATIONS 🧚

these are the ones your subclasses get to play with. protected, not private — so yes, you're invited, but only if you're inheriting. 🙈

• virtual UHashElem* CreateElem() — returns a new UHashElem instance. 💖 and listen: subclasses of UHashTable should redefine this function if they use subclasses of UHashElem. that's not a suggestion, that's the whole point of it existing. periodt.
• virtual int Hash(void* key) — hashes the specified key to return a slot index. 📇 important caveat: this value should be less than the value of the _nslots member variable. don't go past the slots bestie, that's not the vibe.
• virtual boolean Equal(void* key1, void* key2) — returns whether the specified keys are equivalent. 🟰 by default, Equal simply compares the pointers for equality. but subclasses may redefine this operation to make more sophisticated comparisons — so if pointer equality isn't cutting it for you, that's your moment to shine. 👑

🌟 SEE ALSO 🌟

• Iterator(3U)

okay that's the whole page, you ate that. 🍓 before you go: this little beauty comes from the Unidraw distribution, dated 3 October 1990, and it's page UHashTable(3U) in the manual. mwah. 💋✨🎀