---
name: "rhash_new"
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_new"
---

# rhash\_new(3)

allocate a new rhash

## NAME

rhash\_new - allocate a new rhash

## SYNOPSIS

\#include \<roy.h\>

RHash \* rhash\_new (RHashHashFunction *hash\_function*, RHashCompareFunction *compare\_function*);

## DESCRIPTION

Create a new structure to hold a hash.  The functions for hashing the type intended to be used in the table, as well as a function for comparing these types, are provided.

## RETURN VALUE

This function will always succeed in returning a newly allocated rhash structure.  This structure should later be freed using [*rhash\_free*(3)](/rhash_free/3.md).

## HASH FUNCTION

The hash function passed in as the *hash\_function* argument to [*rhash\_new*(3)](/rhash_new/3.md) is defined as:

typedef unsigned long (\*RHashHashFunction) (const void \**key*);

and should be declared as:

unsigned long rhash\_hash\_function (const void \**key*);

This function will then cast *key* to the appropriate structure used in the hash table, and then perform a hashing algorithm on the key stored within the structure.

This algorithm should attempt to return a unique unsigned long integer corresponding to the key.

Passing in a NULL for this argument will cause [*rhash\_new*(3)](/rhash_new/3.md) to use the value of the pointer key passed to insert/lookup as the key.

## COMPARE FUNCTION

The compare function passed in as the *compare\_function* argument to [*rhash\_new*(3)](/rhash_new/3.md) is defined as:

typedef unsigned int (\*RHashCompareFunction) (const void \**entry\_key*, const void \**key*);

and should be declared as:

unsigned int rhash\_compare\_function (const void \**entry\_key*, const void \**key*);

The *entry\_key* should then be cast to the key type being used, as should *key*.  *key* will be the key as passed into the [*rhash\_lookup*(3)](/rhash_lookup/3.md) function, and *entry\_key* will be the key of the entry being tested. This function should then return TRUE if the two keys are equal, or FALSE if they are not.

Passing in a NULL for this argument will cause RHash to use the value of the pointer passed in as they key as an unsigned long integer, which it will then compare directly as an integer to the entries.

## ERRORS

The [*rhash\_new*(3)](/rhash_new/3.md) call will never return any failure condition. Any out of memory issues are delt with by [*rmem*(3)](/rmem/3.md) functions.

## SEE ALSO

[*rhash*(3)](/rhash/3.md), [*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\_remove*(3)](/rhash_remove/3.md), [*rhash\_remove\_entry*(3)](/rhash_remove_entry/3.md),  [*roy*(3)](/roy/3.md)