Refcounted hash map with caller-supplied hash and equality functions and optional per-key / per-value destroy notifiers. More...

Files
file	rhashtable.h
	Refcounted hash-map container.

Macros
#define	R_HASH_TABLE_IS_SUCCESS(err) (err <= R_HASH_TABLE_OK)
	Convenience predicate: `TRUE` iff `err` is a success code.

#define	R_HASH_TABLE_IS_ERROR(err) (err > R_HASH_TABLE_OK)
	Convenience predicate: `TRUE` iff `err` is an error code.

#define	r_hash_table_new(hash, equal) r_hash_table_new_full (hash, equal, NULL, NULL)
	Convenience: construct a hash table with no destroy notifiers (caller owns both keys and values).

#define	r_hash_table_ref r_ref_ref
	Increment the table's refcount.

#define	r_hash_table_unref r_ref_unref
	Decrement the table's refcount; clears all entries when it reaches zero.

#define	r_hash_table_remove_all_values(ht, val) r_hash_table_remove_with_func (ht, r_hash_table_remove_func_value, val)
	Convenience: remove every entry whose value pointer matches `val`.

Typedefs
typedef struct RHashTable	RHashTable
	Opaque refcounted hash table.

Enumerations
enum	RHashTableError { R_HASH_TABLE_REPLACE = -1 , R_HASH_TABLE_OK = 0 , R_HASH_TABLE_INVAL , R_HASH_TABLE_NOT_FOUND , R_HASH_TABLE_ERROR }
	Result code for hash-table operations. More...

Functions
RHashTable *	r_hash_table_new_full (RHashFunc hash, REqualFunc equal, RDestroyNotify keynotify, RDestroyNotify valuenotify)
	Construct a hash table with custom hash / equality and optional per-side destroy notifiers.

rsize	r_hash_table_size (RHashTable *ht)
	Number of entries currently in the table.

rsize	r_hash_table_current_alloc_size (RHashTable *ht)
	Allocated bucket count; useful for sizing diagnostics.

rsize	r_hash_table_max_probe (RHashTable *ht)
	Worst-case unsuccessful-probe length; diagnostic for home distribution (small means keys are well spread across the buckets).

RHashTableError	r_hash_table_insert (RHashTable *ht, rpointer key, rpointer value)
	Insert or replace (key, value).

rpointer	r_hash_table_lookup (RHashTable *ht, rconstpointer key)
	Return the value associated with `key`, or `NULL`.

RHashTableError	r_hash_table_lookup_full (RHashTable ht, rconstpointer key, rpointer keyout, rpointer *valueout)
	Look up `key`, returning both the stored key and value.

RHashTableError	r_hash_table_contains (RHashTable *ht, rconstpointer key)
	`R_HASH_TABLE_OK` iff `key` is present, `R_HASH_TABLE_NOT_FOUND` otherwise.

void	r_hash_table_remove_all (RHashTable *ht)
	Remove every entry, invoking destroy notifiers.

RHashTableError	r_hash_table_remove (RHashTable *ht, rconstpointer key)
	Remove the entry for `key`; destroy notifiers run.

RHashTableError	r_hash_table_remove_full (RHashTable ht, rconstpointer key, rpointer keyout, rpointer *valueout)
	Remove the entry for `key`, running its destroy notifiers (as r_hash_table_remove), and also report the removed key / value via `keyout` / `valueout`.

RHashTableError	r_hash_table_steal (RHashTable ht, rconstpointer key, rpointer keyout, rpointer *valueout)
	Remove the entry for `key` without running its destroy notifiers, handing ownership of the key / value to the caller via `keyout` / `valueout` (the caller must free them).

rboolean	r_hash_table_remove_func_value (rpointer key, rpointer value, rpointer user)
	Filter callback that matches by value identity.

RHashTableError	r_hash_table_remove_with_func (RHashTable *ht, RKeyValueFuncReturn func, rpointer user)
	Remove all entries for which `func` returns `TRUE`.

RHashTableError	r_hash_table_foreach (RHashTable *ht, RKeyValueFunc func, rpointer user)
	Iterate every (key, value) pair in the table.

Detailed Description

Refcounted hash map with caller-supplied hash and equality functions and optional per-key / per-value destroy notifiers.

Keys and values are stored as rpointer, leaving the ownership model to the caller. Pass RDestroyNotify callbacks at construction time and the table will invoke them on remove / remove_all / unref; pass NULL for caller-owned keys or values.

Pre-built hash / equality pairs for the common key types live in Hash functions (r_direct_hash / r_direct_equal for pointer-identity keys, r_str_hash / r_str_equal for NUL-terminated strings). See Dictionary (string-keyed hashtable) for the string-keyed convenience wrapper.

Enumeration Type Documentation

◆ RHashTableError

enum RHashTableError

Result code for hash-table operations.

Non-positive values (REPLACE / OK) are successes; REPLACE flags that an existing entry was overwritten by r_hash_table_insert.

Enumerator
R_HASH_TABLE_REPLACE	Insert overwrote an existing entry.
R_HASH_TABLE_OK	Operation completed successfully.
R_HASH_TABLE_INVAL	Invalid argument.
R_HASH_TABLE_NOT_FOUND	Key not present.
R_HASH_TABLE_ERROR	Internal failure.

Function Documentation

◆ r_hash_table_foreach()

RHashTableError r_hash_table_foreach	(	RHashTable *	ht,
		RKeyValueFunc	func,
		rpointer	user
	)

Iterate every (key, value) pair in the table.

func may not insert into or remove from ht; use r_hash_table_remove_with_func for filtered removal.

◆ r_hash_table_insert()

RHashTableError r_hash_table_insert	(	RHashTable *	ht,
		rpointer	key,
		rpointer	value
	)

Insert or replace (key, value).

Returns R_HASH_TABLE_REPLACE if an existing entry was overwritten (existing key + value run through their destroy notifiers), R_HASH_TABLE_OK on fresh insert.

◆ r_hash_table_lookup_full()

RHashTableError r_hash_table_lookup_full	(	RHashTable *	ht,
		rconstpointer	key,
		rpointer *	keyout,
		rpointer *	valueout
	)

Look up key, returning both the stored key and value.

Useful when the caller needs the table-owned key (e.g. to know which of several equivalent keys is present).

◆ r_hash_table_new_full()

RHashTable * r_hash_table_new_full	(	RHashFunc	hash,
		REqualFunc	equal,
		RDestroyNotify	keynotify,
		RDestroyNotify	valuenotify
	)

Construct a hash table with custom hash / equality and optional per-side destroy notifiers.

Parameters

hash	Hash function applied to each key.
equal	Equality comparator paired with `hash`.
keynotify	Destroy notifier for keys, or `NULL`.
valuenotify	Destroy notifier for values, or `NULL`.

◆ r_hash_table_remove_full()

RHashTableError r_hash_table_remove_full	(	RHashTable *	ht,
		rconstpointer	key,
		rpointer *	keyout,
		rpointer *	valueout
	)

Remove the entry for key, running its destroy notifiers (as r_hash_table_remove), and also report the removed key / value via keyout / valueout.

Note: If destroy notifiers are registered they have already freed the key / value by the time this returns, so the out-params are only safe to dereference when no notifier is set. To take ownership without running the notifiers, use r_hash_table_steal.

◆ r_hash_table_remove_func_value()

rboolean r_hash_table_remove_func_value	(	rpointer	key,
		rpointer	value,
		rpointer	user
	)

Filter callback that matches by value identity.

Internal helper used by r_hash_table_remove_all_values; exported so callers can pass it directly to r_hash_table_remove_with_func without naming a private lambda.

◆ r_hash_table_remove_with_func()

RHashTableError r_hash_table_remove_with_func	(	RHashTable *	ht,
		RKeyValueFuncReturn	func,
		rpointer	user
	)

Remove all entries for which func returns TRUE.

func is invoked for each entry with the supplied user cookie; on TRUE the entry is removed (destroy notifiers run).

Files

Macros

Typedefs

Enumerations

Functions