---
name: "rhash"
section: "3"
platform: "linux"
package: "libroy-dev"
version: "1.0.8-1"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/rhash/3"
---

# rhash(3)

Roy hash table

## NAME

rhash - Roy hash table

## SYNOPSIS

\#include \<roy.h\>

## DESCRIPTION

A memory and speed efficent hash table implementation designed for small as well as a large number of entries. The entries are defined by the programmer, as well as allocated by the programmer prior to insertion into the hash table.

Hash tables are an excellent choice for storing/retrieving by key as the time to perform insert and lookups is nearly linear regardless of the number of entries.  The RHash can perform a lookup as fast as the average lookup of a linked list with 3 entries, or a binary tree with 7 entries, and the RHash structure uses only 20 bytes when empty (on 32 bit platforms).

- The User Defined Entry

  In order to use this hash table, you must create your own structure to be used as the entries in the hash table.  This structure \*MUST\* start with the first entry as 'RHASH\_HEADER;'.

  ```
          struct FooEntry {
                  RHASH_HEADER;
                  char *foodata;
                  /* ... */
          };
  ```

  You can create the toplevel RHash structure by using [*rhash\_new*(3)](/rhash_new/3.md) (free with [*rhash\_free*(3)](/rhash_free/3.md)), or you can allocate the hash structure yourself, and call RHASH\_INIT(hash) on it.  This initializes hash to be totally empty.

- RHASH\_INIT (hash)

  Initialize a newly created hash table. The 'hash' argument needs to be an RHash struct.

  ```
          {
                  RHash hash;
  ```

  ```
                  RHASH_INIT (&hash);
                  /* ... rhash functions ... */
          }
  ```

- RHASH\_DESTRUCT (hash)

  Free up the table pointing to the entries and reset the hash table completely empty.

  ```
          {
                  RHash hash;
  ```

  ```
                  RHASH_INIT (&hash);
                  /* ... */
                  RHASH_DESTRUCT (&hash);
          }
  ```

- RHASH\_FOREACH (hash, entry)

  This macro walks through a hash, assigning 'entry' to a hash entry through each iteration.  Caution while the programmer can use `"break"`, `"continue"`, or `"goto"` safely, the order of the entries is not defined. No rhash function/macro save [*rhash\_remove\_entry*(3)](/rhash_remove_entry/3.md) can be called safely inside the RHASH\_FOREACH macro. Do not use, [*rhash\_remove*(3)](/rhash_remove/3.md) in place of [*rhash\_remove\_entry*(3)](/rhash_remove_entry/3.md).

  ```
          RHASH_FOREACH (hash, entry) {
                  if (entry->foodata == NULL)
                          break;
                  printf ("Data: %s.\n", entry->foodata);
          } RFOREACH_CLOSE;
  ```

  ```
          /* Freeing entries out of a hashtable. */
          RHASH_FOREACH (hash, entry) {
                  rhash_remove_entry (hash, entry);
                  rmem_free (entry);
          } RFOREACH_CLOSE;
  ```

  ```
          /* Now free up the hashtable. */
          rhash_free (hash);
  ```

## SEE ALSO

[*rhash\_entry\_getkey*(3)](/rhash_entry_getkey/3.md), [*rhash\_entry\_setkey*(3)](/rhash_entry_setkey/3.md),  [*rhash\_free*(3)](/rhash_free/3.md), [*rhash\_insert*(3)](/rhash_insert/3.md),  [*rhash\_len*(3)](/rhash_len/3.md), [*rhash\_lookup*(3)](/rhash_lookup/3.md),  [*rhash\_lookup\_next*(3)](/rhash_lookup_next/3.md), [*rhash\_new*(3)](/rhash_new/3.md),  [*rhash\_remove*(3)](/rhash_remove/3.md), [*rhash\_remove\_entry*(3)](/rhash_remove_entry/3.md),  [*roy*(3)](/roy/3.md)