ZHASHX(3)

💖 ZHASHX(3) 💖

okay bestie, this is the ZHASHX(3) page from the CZMQ Manual. it's giving extended generic hash container energy, and we're gonna read it together. ✨

---

✨ NAME ✨

zhashx — Class for extended generic hash container 💅

---

🌸 SYNOPSIS 🌸

first up, the vibe check: this is a stable class, and it may not change except for emergencies. It is provided in stable builds. also, this class has draft methods, which may change over time. They are not in stable releases, by default. Use --enable-drafts to enable. periodt. 💖

🧚 typedefs 🧚

• zhashx_destructor_fn — Destroy an item. it's the callback that takes void **item and sends it to the void. 💀

typedef void (zhashx_destructor_fn) (
    void **item);

• zhashx_duplicator_fn — Duplicate an item. takes const void *item and gives you a copy, no cap. ✨

typedef void * (zhashx_duplicator_fn) (
    const void *item);

• zhashx_comparator_fn — Compare two items, for sorting. takes const void *item1, const void *item2 and returns an int. lowkey the referee of the group. 🧚

typedef int (zhashx_comparator_fn) (
    const void *item1, const void *item2);

• zhashx_free_fn — Destroy an item. takes void *data and frees it. 💅

typedef void (zhashx_free_fn) (
    void *data);

• zhashx_hash_fn — Hash function for keys. takes const void *key and returns size_t. it's the math girlie. 🔥

typedef size_t (zhashx_hash_fn) (
    const void *key);

• zhashx_serializer_fn — Serializes an item to a longstr. The caller takes ownership of the newly created object. takes const void *item and returns char *. 👑

typedef char * (zhashx_serializer_fn) (
    const void *item);

• zhashx_deserializer_fn — Deserializes a longstr into an item. The caller takes ownership of the newly created object. takes const char *item_str and returns void *. 🌈

typedef void * (zhashx_deserializer_fn) (
    const char *item_str);

🛠️ functions 🛠️

• zhashx_new — Create a new, empty hash container. it's the birth of a legend. ✨

CZMQ_EXPORT zhashx_t *
    zhashx_new (void);

• zhashx_unpack — Unpack binary frame into a new hash table. Packed data must follow format defined by zhashx_pack. Hash table is set to autofree. An empty frame unpacks to an empty hash table. 🎀

CZMQ_EXPORT zhashx_t *
    zhashx_unpack (zframe_t *frame);

• zhashx_destroy — Destroy a hash container and all items in it. it's the end, bestie. 💀

CZMQ_EXPORT void
    zhashx_destroy (zhashx_t **self_p);

• zhashx_insert — Insert item into hash table with specified key and item. If key is already present returns -1 and leaves existing item unchanged. Returns 0 on success. so if she's already there, she stays. no cap. 🔥

CZMQ_EXPORT int
    zhashx_insert (zhashx_t *self, const void *key, void *item);

• zhashx_update — Update or insert item into hash table with specified key and item. If the key is already present, destroys old item and inserts new one. If you set a container item destructor, this is called on the old value. If the key was not already present, inserts a new item. Sets the hash cursor to the new item. it's giving main character energy. 👑

CZMQ_EXPORT void
    zhashx_update (zhashx_t *self, const void *key, void *item);

• zhashx_delete — Remove an item specified by key from the hash table. If there was no such item, this function does nothing. ghosting, but politely. 🙈

CZMQ_EXPORT void
    zhashx_delete (zhashx_t *self, const void *key);

• zhashx_purge — Delete all items from the hash table. If the key destructor is set, calls it on every key. If the item destructor is set, calls it on every item. it's a full reset, periodt. 💅

CZMQ_EXPORT void
    zhashx_purge (zhashx_t *self);

• zhashx_lookup — Return the item at the specified key, or null. if she's not there, you get nothing. 😭

CZMQ_EXPORT void *
    zhashx_lookup (zhashx_t *self, const void *key);

• zhashx_rename — Reindexes an item from an old key to a new key. If there was no such item, does nothing. Returns 0 if successful, else -1. rebranding era. ✨

CZMQ_EXPORT int
    zhashx_rename (zhashx_t *self, const void *old_key, const void *new_key);

• zhashx_freefn — Set a free function for the specified hash table item. When the item is destroyed, the free function, if any, is called on that item. Use this when hash items are dynamically allocated, to ensure that you don't have memory leaks. You can pass 'free' or NULL as a free_fn. Returns the item, or NULL if there is no such item. no leaks in this house. 🧚

CZMQ_EXPORT void *
    zhashx_freefn (zhashx_t *self, const void *key, zhashx_free_fn free_fn);

• zhashx_size — Return the number of keys/items in the hash table. she's counting. 🔢

CZMQ_EXPORT size_t
    zhashx_size (zhashx_t *self);

• zhashx_keys — Return a zlistx_t containing the keys for the items in the table. Uses the key_duplicator to duplicate all keys and sets the key_destructor as destructor for the list. Caller owns return value and must destroy it when done. you better take care of her. 🫶

CZMQ_EXPORT zlistx_t *
    zhashx_keys (zhashx_t *self);

• zhashx_values — Return a zlistx_t containing the values for the items in the table. Uses the duplicator to duplicate all items and sets the destructor as destructor for the list. Caller owns return value and must destroy it when done. same energy. 💖

CZMQ_EXPORT zlistx_t *
    zhashx_values (zhashx_t *self);

• zhashx_first — Simple iterator; returns first item in hash table, in no given order, or NULL if the table is empty. This method is simpler to use than the foreach() method, which is deprecated. To access the key for this item use zhashx_cursor(). NOTE: do NOT modify the table while iterating. ⚠️

CZMQ_EXPORT void *
    zhashx_first (zhashx_t *self);

• zhashx_next — Simple iterator; returns next item in hash table, in no given order, or NULL if the last item was already returned. Use this together with zhashx_first() to process all items in a hash table. If you need the items in sorted order, use zhashx_keys() and then zlistx_sort(). To access the key for this item use zhashx_cursor(). NOTE: do NOT modify the table while iterating. ⚠️

CZMQ_EXPORT void *
    zhashx_next (zhashx_t *self);

• zhashx_cursor — After a successful first/next method, returns the key for the item that was returned. This is a constant string that you may not modify or deallocate, and which lasts as long as the item in the hash. After an unsuccessful first/next, returns NULL. she's the locator. 🔍

CZMQ_EXPORT const void *
    zhashx_cursor (zhashx_t *self);

• zhashx_comment — Add a comment to hash table before saving to disk. You can add as many comment lines as you like. These comment lines are discarded when loading the file. If you use a null format, all comments are deleted. it's just for the aesthetic. 🎀

CZMQ_EXPORT void
    zhashx_comment (zhashx_t *self, const char *format, ...) CHECK_PRINTF (2);

• zhashx_save — Save hash table to a text file in name=value format. Hash values must be printable strings; keys may not contain '=' character. Returns 0 if OK, else -1 if a file error occurred. ✨

CZMQ_EXPORT int
    zhashx_save (zhashx_t *self, const char *filename);

• zhashx_load — Load hash table from a text file in name=value format; hash table must already exist. Hash values must printable strings; keys may not contain '=' character. Returns 0 if OK, else -1 if a file was not readable. 📂

CZMQ_EXPORT int
    zhashx_load (zhashx_t *self, const char *filename);

• zhashx_refresh — When a hash table was loaded from a file by zhashx_load, this method will reload the file if it has been modified since, and is "stable", i.e. not still changing. Returns 0 if OK, -1 if there was an error reloading the file. 🔄

CZMQ_EXPORT int
    zhashx_refresh (zhashx_t *self);

• zhashx_pack — Serialize hash table to a binary frame that can be sent in a message. The packed format is compatible with the 'dictionary' type defined in http://rfc.zeromq.org/spec:35/FILEMQ, and implemented by zproto:

; A list of name/value pairs
dictionary      = dict-count *( dict-name dict-value )
dict-count      = number-4
dict-value      = longstr
dict-name       = string

; Strings are always length + text contents
longstr         = number-4 *VCHAR
string          = number-1 *VCHAR

; Numbers are unsigned integers in network byte order
number-1        = 1OCTET
number-4        = 4OCTET

Comments are not included in the packed data. Item values MUST be strings. Caller owns return value and must destroy it when done.

CZMQ_EXPORT zframe_t *
    zhashx_pack (zhashx_t *self);

• zhashx_dup — Make a copy of the list; items are duplicated if you set a duplicator for the list, otherwise not. Copying a null reference returns a null reference. Note that this method's behavior changed slightly for CZMQ v3.x, as it does not set nor respect autofree. It does however let you duplicate any hash table safely. The old behavior is in zhashx_dup_v2. Caller owns return value and must destroy it when done. glow up. 💅

CZMQ_EXPORT zhashx_t *
    zhashx_dup (zhashx_t *self);

• zhashx_set_destructor — Set a user-defined deallocator for hash items; by default items are not freed when the hash is destroyed. 💀

CZMQ_EXPORT void
    zhashx_set_destructor (zhashx_t *self, zhashx_destructor_fn destructor);

• zhashx_set_duplicator — Set a user-defined duplicator for hash items; by default items are not copied when the hash is duplicated. ✨

CZMQ_EXPORT void
    zhashx_set_duplicator (zhashx_t *self, zhashx_duplicator_fn duplicator);

• zhashx_set_key_destructor — Set a user-defined deallocator for keys; by default keys are freed when the hash is destroyed using free(). 🔑

CZMQ_EXPORT void
    zhashx_set_key_destructor (zhashx_t *self, zhashx_destructor_fn destructor);

• zhashx_set_key_duplicator — Set a user-defined duplicator for keys; by default keys are duplicated using strdup. 🔑

CZMQ_EXPORT void
    zhashx_set_key_duplicator (zhashx_t *self, zhashx_duplicator_fn duplicator);

• zhashx_set_key_comparator — Set a user-defined comparator for keys; by default keys are compared using strcmp. The callback function should return zero (0) on matching items. 🧚

CZMQ_EXPORT void
    zhashx_set_key_comparator (zhashx_t *self, zhashx_comparator_fn comparator);

• zhashx_set_key_hasher — Set a user-defined hash function for keys; by default keys are hashed by a modified Bernstein hashing function. 🔥

CZMQ_EXPORT void
    zhashx_set_key_hasher (zhashx_t *self, zhashx_hash_fn hasher);

• zhashx_dup_v2 — Make copy of hash table; if supplied table is null, returns null. Does not copy items themselves. Rebuilds new table so may be slow on very large tables. NOTE: only works with item values that are strings since there's no other way to know how to duplicate the item value. the old way, but still valid. 🧓

CZMQ_EXPORT zhashx_t *
    zhashx_dup_v2 (zhashx_t *self);

• zhashx_test — Self test of this class. 🧪

CZMQ_EXPORT void
    zhashx_test (bool verbose);

🚧 draft methods (inside CZMQ_BUILD_DRAFT_API) 🚧

* Draft method, for development use, may change without warning * — you've been warned, bestie. ⚠️

• zhashx_unpack_own — Same as unpack but uses a user-defined deserializer function to convert a longstr back into item format. ✨

CZMQ_EXPORT zhashx_t *
    zhashx_unpack_own (zframe_t *frame, zhashx_deserializer_fn deserializer);

• zhashx_pack_own — Same as pack but uses a user-defined serializer function to convert items into longstr. Caller owns return value and must destroy it when done. 💅

CZMQ_EXPORT zframe_t *
    zhashx_pack_own (zhashx_t *self, zhashx_serializer_fn serializer);

and the #ifdef wrapper is exactly:

#ifdef CZMQ_BUILD_DRAFT_API
CZMQ_EXPORT zhashx_t *
    zhashx_unpack_own (zframe_t *frame, zhashx_deserializer_fn deserializer);

CZMQ_EXPORT zframe_t *
    zhashx_pack_own (zhashx_t *self, zhashx_serializer_fn serializer);

#endif // CZMQ_BUILD_DRAFT_API

also there's this note at the very end: Please add '@interface' section in './../src/zhashx.c'.

💖 DESCRIPTION 💖

okay bestie so zhashx is an extended hash table container, right? It's like its simpler cousin zhash but with way more ✨functionality✨. More options, more main character energy, more everything. It's giving glow-up. 💅

The hash table always has a size that is prime, and it roughly doubles its size when it's 75% full. So it's always flexing, always making room, never crowded. 🦋

In case of hash collisions, items get chained in a linked list — yes, a whole friendship chain, they all hang out together at the same bucket. And when an overly long chain gets detected (between 1 and 63 items, depending on the table size, bestie), the table size gets increased slightly — up to 5 times before it roughly doubles the size. So it's like, small adjustments first, big moves later. Periodt. 💫

---

🌸 EXAMPLE 🌸

straight from the zhashx_test method, here's the whole vibe in action. Read it, love it, run it, no cap:

zhashx_t *hash = zhashx_new ();
assert (hash);
assert (zhashx_size (hash) == 0);
assert (zhashx_first (hash) == NULL);
assert (zhashx_cursor (hash) == NULL);

//  Insert some items
int rc;
rc = zhashx_insert (hash, "DEADBEEF", "dead beef");
char *item = (char *) zhashx_first (hash);
assert (streq ((char *) zhashx_cursor (hash), "DEADBEEF"));
assert (streq (item, "dead beef"));
assert (rc == 0);
rc = zhashx_insert (hash, "ABADCAFE", "a bad cafe");
assert (rc == 0);
rc = zhashx_insert (hash, "C0DEDBAD", "coded bad");
assert (rc == 0);
rc = zhashx_insert (hash, "DEADF00D", "dead food");
assert (rc == 0);
assert (zhashx_size (hash) == 4);

//  Look for existing items
item = (char *) zhashx_lookup (hash, "DEADBEEF");
assert (streq (item, "dead beef"));
item = (char *) zhashx_lookup (hash, "ABADCAFE");
assert (streq (item, "a bad cafe"));
item = (char *) zhashx_lookup (hash, "C0DEDBAD");
assert (streq (item, "coded bad"));
item = (char *) zhashx_lookup (hash, "DEADF00D");
assert (streq (item, "dead food"));

//  Look for non-existent items
item = (char *) zhashx_lookup (hash, "foo");
assert (item == NULL);

//  Try to insert duplicate items
rc = zhashx_insert (hash, "DEADBEEF", "foo");
assert (rc == -1);
item = (char *) zhashx_lookup (hash, "DEADBEEF");
assert (streq (item, "dead beef"));

//  Some rename tests

//  Valid rename, key is now LIVEBEEF
rc = zhashx_rename (hash, "DEADBEEF", "LIVEBEEF");
assert (rc == 0);
item = (char *) zhashx_lookup (hash, "LIVEBEEF");
assert (streq (item, "dead beef"));

//  Trying to rename an unknown item to a non-existent key
rc = zhashx_rename (hash, "WHATBEEF", "NONESUCH");
assert (rc == -1);

//  Trying to rename an unknown item to an existing key
rc = zhashx_rename (hash, "WHATBEEF", "LIVEBEEF");
assert (rc == -1);
item = (char *) zhashx_lookup (hash, "LIVEBEEF");
assert (streq (item, "dead beef"));

//  Trying to rename an existing item to another existing item
rc = zhashx_rename (hash, "LIVEBEEF", "ABADCAFE");
assert (rc == -1);
item = (char *) zhashx_lookup (hash, "LIVEBEEF");
assert (streq (item, "dead beef"));
item = (char *) zhashx_lookup (hash, "ABADCAFE");
assert (streq (item, "a bad cafe"));

//  Test keys method
zlistx_t *keys = zhashx_keys (hash);
assert (zlistx_size (keys) == 4);
zlistx_destroy (&keys);

zlistx_t *values = zhashx_values (hash);
assert (zlistx_size (values) == 4);
zlistx_destroy (&values);

//  Test dup method
zhashx_t *copy = zhashx_dup (hash);
assert (zhashx_size (copy) == 4);
item = (char *) zhashx_lookup (copy, "LIVEBEEF");
assert (item);
assert (streq (item, "dead beef"));
zhashx_destroy (&copy);

//  Test pack/unpack methods
zframe_t *frame = zhashx_pack (hash);
copy = zhashx_unpack (frame);
zframe_destroy (&frame);
assert (zhashx_size (copy) == 4);
item = (char *) zhashx_lookup (copy, "LIVEBEEF");
assert (item);
assert (streq (item, "dead beef"));
zhashx_destroy (&copy);

#ifdef CZMQ_BUILD_DRAFT_API
//  Test own pack/unpack methods
zhashx_t *own_hash = zhashx_new ();
zhashx_set_destructor (own_hash, s_test_destroy_int);
assert (own_hash);
int *val1 = (int *) zmalloc (sizeof (int));
int *val2 = (int *) zmalloc (sizeof (int));
*val1 = 25;
*val2 = 100;
zhashx_insert (own_hash, "val1", val1);
zhashx_insert (own_hash, "val2", val2);
frame = zhashx_pack_own (own_hash, s_test_serialize_int);
copy = zhashx_unpack_own (frame, s_test_deserialze_int);
zhashx_set_destructor (copy, s_test_destroy_int);
zframe_destroy (&frame);
assert (zhashx_size (copy) == 2);
assert (*((int *) zhashx_lookup (copy, "val1")) == 25);
assert (*((int *) zhashx_lookup (copy, "val2")) == 100);
zhashx_destroy (&copy);
zhashx_destroy (&own_hash);
#endif // CZMQ_BUILD_DRAFT_API

//  Test save and load
zhashx_comment (hash, "This is a test file");
zhashx_comment (hash, "Created by %s", "czmq_selftest");
zhashx_save (hash, ".cache");
copy = zhashx_new ();
assert (copy);
zhashx_load (copy, ".cache");
item = (char *) zhashx_lookup (copy, "LIVEBEEF");
assert (item);
assert (streq (item, "dead beef"));
zhashx_destroy (&copy);
zsys_file_delete (".cache");

//  Delete a item
zhashx_delete (hash, "LIVEBEEF");
item = (char *) zhashx_lookup (hash, "LIVEBEEF");
assert (item == NULL);
assert (zhashx_size (hash) == 3);

//  Check that the queue is robust against random usage
struct {
    char name [100];
    bool exists;
} testset [200];
memset (testset, 0, sizeof (testset));
int testmax = 200, testnbr, iteration;

srandom ((unsigned) time (NULL));
for (iteration = 0; iteration < 25000; iteration++) {
    testnbr = randof (testmax);
    assert (testnbr != testmax);
    assert (testnbr < testmax);
    if (testset [testnbr].exists) {
        item = (char *) zhashx_lookup (hash, testset [testnbr].name);
        assert (item);
        zhashx_delete (hash, testset [testnbr].name);
        testset [testnbr].exists = false;
    }
    else {
        sprintf (testset [testnbr].name, "%x-%x", rand (), rand ());
        if (zhashx_insert (hash, testset [testnbr].name, "") == 0)
            testset [testnbr].exists = true;
    }
}
//  Test 10K lookups
for (iteration = 0; iteration < 10000; iteration++)
    item = (char *) zhashx_lookup (hash, "DEADBEEFABADCAFE");

//  Destructor should be safe to call twice
zhashx_destroy (&hash);
zhashx_destroy (&hash);
assert (hash == NULL);

//  Test randof() limits - should be within (0..testmax)
//  and randomness distribution - should not have (many) zero-counts
//  If there are - maybe the ZSYS_RANDOF_MAX is too big for this platform
//  Note: This test can take a while on systems with weak floating point HW
testmax = 999;
size_t rndcnt[999];
assert ((sizeof (rndcnt)/sizeof(rndcnt[0])) == testmax);
memset (rndcnt, 0, sizeof (rndcnt));
for (iteration = 0; iteration < 10000000; iteration++) {
    testnbr = randof (testmax);
    assert (testnbr != testmax);
    assert (testnbr < testmax);
    assert (testnbr >= 0);
    rndcnt[testnbr]++;
}
int rndmisses = 0;
for (iteration = 0; iteration < testmax; iteration++) {
    if (rndcnt[iteration] == 0) {
        zsys_warning("zhashx_test() : random distribution fault : got 0 hits for %d/%d",
            iteration, testmax);
        rndmisses++;
    }
}
//  Too many misses are suspicious... we can lose half the entries
//  for each bit not used in the assumed ZSYS_RANDOF_MAX...
assert ( (rndmisses < (testmax / 3 )) );

//  Test destructor; automatically copies and frees string values
hash = zhashx_new ();
assert (hash);
zhashx_set_destructor (hash, (zhashx_destructor_fn *) zstr_free);
zhashx_set_duplicator (hash, (zhashx_duplicator_fn *) strdup);
char value [255];
strcpy (value, "This is a string");
rc = zhashx_insert (hash, "key1", value);
assert (rc == 0);
strcpy (value, "Ring a ding ding");
rc = zhashx_insert (hash, "key2", value);
assert (rc == 0);
assert (streq ((char *) zhashx_lookup (hash, "key1"), "This is a string"));
assert (streq ((char *) zhashx_lookup (hash, "key2"), "Ring a ding ding"));
zhashx_destroy (&hash);

//  Test purger and shrinker: no data should end up unreferenced in valgrind
hash = zhashx_new ();
assert (hash);
zhashx_set_destructor (hash, (zhashx_destructor_fn *) zstr_free);
zhashx_set_duplicator (hash, (zhashx_duplicator_fn *) strdup);
char valuep [255];
strcpy (valuep, "This is a string");
rc = zhashx_insert (hash, "key1", valuep);
assert (rc == 0);
strcpy (valuep, "Ring a ding ding");
rc = zhashx_insert (hash, "key2", valuep);
assert (rc == 0);
strcpy (valuep, "Cartahena delenda est");
rc = zhashx_insert (hash, "key3", valuep);
assert (rc == 0);
strcpy (valuep, "So say we all!");
rc = zhashx_insert (hash, "key4", valuep);
assert (rc == 0);
assert (streq ((char *) zhashx_lookup (hash, "key1"), "This is a string"));
assert (streq ((char *) zhashx_lookup (hash, "key2"), "Ring a ding ding"));
assert (streq ((char *) zhashx_lookup (hash, "key3"), "Cartahena delenda est"));
assert (streq ((char *) zhashx_lookup (hash, "key4"), "So say we all!"));
zhashx_purge (hash);
zhashx_destroy (&hash);

#if defined (__WINDOWS__)
zsys_shutdown();
#endif

ok that was a LOT of code bestie but like, every single line matters. Don't skip it. It's the whole test suite vibe check. 🔥

---

🎀 AUTHORS 🎀

The czmq manual was written by the authors in the AUTHORS file. So if you're looking for who to thank, that's where the credits roll. 👑

---

🌈 RESOURCES 🌈

Main web site: (yes, the page just says that, bestie — that's the resource)

Report bugs to the email zeromq-dev@lists.zeromq.org[1] 🐛

---

💜 COPYRIGHT 💜

Copyright (c) the Contributors as noted in the AUTHORS file. This file is part of CZMQ, the high-level C binding for 0MQ: http://czmq.zeromq.org. This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. LICENSE included with the czmq distribution.

fr fr, read the license, it's the law but make it cute 💅

---

⭐ NOTES ⭐

1. zeromq-dev@lists.zeromq.org — mailto:zeromq-dev@lists.zeromq.org

---

and that's a wrap bestie!! 🫶 this was CZMQ 4.2.1, dated 01/16/2026, aka ZHASHX(3) — go forth and hash slay 👑✨💖