fixes #1740 Public ID hash API

This includes a manual page documenting the entire set of
functions in one step.  The hash is 64-bit based for now, to
be maximally flexible.  An internal 32-bit convenience for the
common internal use is also provided (not public).

The public API includes a test suite.

1 files changed, 27 insertions, 0 deletions

diff --git a/src/supplemental/idhash/idhash.h b/src/supplemental/idhash/idhash.h
new file mode 100644
index 00000000..5fd8f235
--- /dev/null
+++ b/src/supplemental/idhash/idhash.h
@@ -0,0 +1,27 @@
+//
+// Copyright 2023 Staysail Systems, Inc. <info@staysail.tech>
+//
+// This software is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+#ifndef NNG_SUPPLEMENTAL_IDHASH_IDHASH_H
+#define NNG_SUPPLEMENTAL_IDHASH_IDHASH_H
+
+#include <nng/nng.h>
+
+typedef struct nng_id_map_s nng_id_map;
+
+#define NNG_MAP_RANDOM 1
+
+NNG_DECL int nng_id_map_alloc(
+    nng_id_map **map, uint64_t lo, uint64_t hi, int flags);
+NNG_DECL void  nng_id_map_free(nng_id_map *map);
+NNG_DECL void *nng_id_get(nng_id_map *, uint64_t);
+NNG_DECL int   nng_id_set(nng_id_map *, uint64_t, void *);
+NNG_DECL int   nng_id_alloc(nng_id_map *, uint64_t *, void *);
+NNG_DECL int   nng_id_remove(nng_id_map *, uint64_t);
+
+#endif // NNG_SUPPLEMENTAL_IDHASH_IDHASH_H