ici::doc::pod3::sdrhash(3)

📦 version 3.2.1, in ubuntu jammy

💖 sdrhash — the ICI library functions page, but make it make sense 💖

okay bestie, pull up a chair, we're talking about sdrhash from the ICI library functions. it's a (3) manpage, it's all about hash tables in an SDR, and honestly? it's giving organized. let's go 🦋

✨ NAME ✨

sdrhash — Simple Data Recorder hash table management functions 🎀

✨ SYNOPSIS ✨

#include "sdr.h"

Object  sdr_hash_create        (Sdr sdr, int keyLength,
                                    int estNbrOfEntries,
                                    int meanSearchLength);
int     sdr_hash_insert        (Sdr sdr, Object hash, char *key,
                                    Address value, Object *entry);
int     sdr_hash_delete_entry  (Sdr sdr, Object entry);
int     sdr_hash_entry_value   (Sdr sdr, Object hash, Object entry);
int     sdr_hash_retrieve      (Sdr sdr, Object hash, char *key,
                                    Address *value, Object *entry);
int     sdr_hash_count         (Sdr sdr, Object hash);
int     sdr_hash_revise        (Sdr sdr, Object hash, char *key,
                                    Address value);
int     sdr_hash_remove        (Sdr sdr, Object hash, char *key,
                                    Address *value);
int     sdr_hash_destroy       (Sdr sdr, Object hash);

like yes, that's nine functions, we're gonna get to all of them, don't scroll 💅

✨ DESCRIPTION ✨

so the SDR hash functions manage hash table objects in an SDR. that's the whole vibe. hash table objects, inside an SDR. 🫶

hash tables associate values with keys. a value is always in the form of an SDR Address — nominally the address of some stored object identified by the associated key, but fr fr the actual significance of a value may be anything that fits into a long. a key is always an array of from 1 to 255 bytes, which may have any semantics at all. anything. no notes. 🌈

keys must be unique. no two distinct entries in an SDR hash table may have the same key. any attempt to insert a duplicate entry in an SDR hash table will be rejected. the table said no 💀

all keys must be of the same length, and that length must be declared at the time the hash table is created. and listen — invoking a hash table function with a key that is shorter than the declared length will have unpredictable results. unpredictable!! we don't do that. 🙈

⚠️ bestie warning: short key = unpredictable results. that's not a vibe, that's a bug you wrote yourself.

an SDR hash table is an array of linked lists. the location of a given value in the hash table is automatically determined by:

  1. computing a "hash" of the key
  2. dividing the hash by the number of linked lists in the array
  3. using the remainder as an index to the corresponding linked list
  4. then sequentially searching through the list entries until the entry with the matching key is found

the way that's literally just a hash table. iconic algorithm behavior 👑

the number of linked lists in the array is automatically computed at the time the hash table is created, based on the estimated maximum number of entries you expect to store in the table and the mean linked list length (i.e., mean search time) you prefer. increasing the maximum number of entries in the table and decreasing the mean linked list length both tend to increase the amount of SDR heap space occupied by the hash table. so like, more entries + shorter lists = more heap. tradeoff queen 🌸

🎀 the functions 🎀

  • Object sdr_hash_create(Sdr sdr, int keyLength, int estNbrOfEntries, int meanSearchLength) — creates an SDR hash table. returns the SDR address of the new hash table on success, zero on any error. ✨
  • int sdr_hash_insert(Sdr sdr, Object hash, char *key, Address value, Object *entry) — inserts an entry into the hash table identified by hash. on success, places the address of the new hash table entry in entry and returns zero. returns -1 on any error. 💖
  • int sdr_hash_delete_entry(Sdr sdr, Object entry) — deletes the hash table entry identified by entry. returns zero on success, -1 on any error. bye bye entry 👋
  • Address sdr_hash_entry_value(Sdr sdr, Object hash, Object entry) — returns the value of the hash table entry identified by entry. 🍓
  • int sdr_hash_retrieve(Sdr sdr, Object hash, char *key, Address *value, Object *entry) — searches for the value associated with key in this hash table, storing it in value if found. if the entry matching key was found, places the address of the hash table entry in entry and returns 1. returns zero if no such entry exists, -1 on any other failure. found it bestie 🔥
  • int sdr_hash_count(Sdr sdr, Object hash) — returns the number of entries in the hash table identified by hash. math! 🧚
  • int sdr_hash_revise(Sdr sdr, Object hash, char *key, Address value) — searches for the hash table entry matching key in this hash table, replacing the associated value with value if found. returns 1 if the entry matching key was found, zero if no such entry exists, -1 on any other failure. glow up that value 💅
  • int sdr_hash_remove(Sdr sdr, Object hash, char *key, Address *value) — searches for the hash table entry matching key in this hash table; if the entry is found, stores its value in value, deletes the entry, and returns 1. returns zero if no such entry exists, -1 on any other failure. gone, reduced to atoms 💀
  • void sdr_hash_destroy(Sdr sdr, Object hash); — destroys hash, destroying all entries in all linked lists of the array and destroying the hash table array structure itself. 🧨
🚨 DO NOT use sdr_free() to destroy a hash table, as this would leave the hash table's content allocated yet unreferenced. do not do it. i am begging. that's a memory leak with main character energy and we are NOT casting it. 😭

✨ SEE ALSO ✨

and that's the page!! this one is from perl v5.24.1, dated 2016-07-07, under the ici::doc::pod3::sdrhash(3) header — so yeah, vintage, but the hash tables still ate. go build something, bestie 💜🦋✨

📦 where this page comes from