libtar_hash_new(3)

💖 libtar_hash_new — hash table routines 💖

okay bestie, so this is libtar_hash_new(3) — section 3 of the C Library Calls manual, the one where all the fun little C library stuff lives. it's a whole squad of hash table routines and honestly? they ate. 🫶

---

✨ NAME ✨

libtar_hash_new, libtar_hash_free, libtar_hash_next, libtar_hash_prev, libtar_hash_getkey, libtar_hash_search, libtar_hash_add, libtar_hash_del — hash table routines, the whole friend group 💅

---

🌸 SYNOPSIS 🌸

#include <libtar.h>

libtar_hash_t *libtar_hash_new(int num, int (*hashfunc)());
void libtar_hash_free(libtar_hash_t *h, void (*freefunc)());
int libtar_hash_next(libtar_hash_t *h, libtar_hashptr_t *hp);
int libtar_hash_prev(libtar_hash_t *h, libtar_hashptr_t *hp);
int libtar_hash_search(libtar_hash_t *h, libtar_hashptr_t *hp, void
*data, int (*matchfunc)());
int libtar_hash_getkey(libtar_hash_t *h, libtar_hashptr_t *hp, void
*data, int (*matchfunc)());
int libtar_hash_add(libtar_hash_t *h, void *data);
int libtar_hash_del(libtar_hash_t *h, libtar_hashptr_t *hp);

---

🦋 DESCRIPTION 🦋

okay so let's go function by function, no cap. every single one matters, i'm not skipping a single one of my girls. 💜

🎀 libtar_hash_new()

creates a new hash with num buckets, using the hash function pointed to by hashfunc. and if hashfunc is NULL? don't even stress — a default hash function designed for 7-bit ASCII strings gets used instead. iconic behaviour honestly. ✨

🎀 libtar_hash_free()

deallocates all memory associated with the hash structure h. and if freefunc is not NULL, it gets called to free the memory associated with each node in the hash. so like, it's not just yeeting the table, it's cleaning up every single node too. main character energy fr fr. 🧹💖

🎀 libtar_hash_next() and libtar_hash_prev()

these two are your little tour guides — they're used to iterate through the hash. 🚶♀️

now the libtar_hashptr_t structure has exactly two fields:

• bucket — indicates the current bucket in the hash
• node — a pointer to the current node in the current bucket

and here's the trick bestie: to start at the beginning or the end of the hash, the caller should initialize hp.bucket to -1 and hp.node to NULL. that's the vibe check you gotta pass first, iykyk. ⭐

🎀 libtar_hash_search()

this one searches iteratively through the hash h until it finds a node whose contents match data using the matching function matchfunc. and where does the searching begin? at the location pointed to by hp, bestie. it just keeps going until it finds its match. 💀✨

🎀 libtar_hash_getkey()

this one is smarter and i love her for it. she uses the hash function associated with h to figure out which bucket data should be in — and then searches only that bucket for a matching node using matchfunc. no wandering around the whole table, she goes straight there. searching begins at the location pointed to by hp. queen behaviour. 👑

🎀 libtar_hash_add()

adds data into hash h. simple. slay. 💅

🎀 libtar_hash_del()

removes the node referenced by hp. bye bestie 👋

---

🔥 RETURN VALUE 🔥

here's what each one gives you back, no gatekeeping:

• libtar_hash_new() returns a pointer to the new hash structure, or NULL on error. 😭
• libtar_hash_next() and libtar_hash_prev() return 1 when valid data is returned, and 0 at the end of the hash. so 0 is literally just "that's all folks", not a fail. 🌈
• libtar_hash_getkey() and libtar_hash_search() return 1 when a match is found, or 0 otherwise.
• libtar_hash_add() returns 0 on success, or -1 on error (and sets errno).
• libtar_hash_del() returns 0 on success, or -1 on error (and sets errno).

heads up bestie: -1 means something went sideways and errno got set. don't ignore her, she's trying to tell you something. 🚨

---

👀 SEE ALSO 👀

• libtar_list_new(3) — her cousin, also a baddie 💖

---

and that's the whole page, periodt. 💅 this was brought to you by the University of Illinois, dated Jan 2000 — yes she's vintage, she's a classic, she's been serving hash tables since Y2K and she's still thriving. obsessed. 🎀✨🦋