Key-value pointer array

Growable, refcounted ordered array of (key, value) pointer pairs. More...

Files
file	rkvptrarray.h
	Growable refcounted array of (key, value) pointer pairs.

Data Structures
struct	RKVPtrArray
	Public definition of RKVPtrArray. More...

Macros
#define	R_KV_PTR_ARRAY_INVALID_IDX   RSIZE_MAX
	Sentinel returned by lookup helpers when no match is found.

Lifecycle
void	r_kv_ptr_array_init (RKVPtrArray *array, REqualFunc eqfunc)
	Initialise an embedded / stack array with the given equality function.
void	r_kv_ptr_array_clear (RKVPtrArray *array)
	Drop every pair, run destroy notifiers, release storage.
RKVPtrArray *	r_kv_ptr_array_new_sized (rsize size, REqualFunc eqfunc)
	Heap-allocate an array with size initial slots and the caller's equality function.
#define	R_KV_PTR_ARRAY_INIT_WITH_FUNC(eqfunc)   { R_REF_STATIC_INIT (NULL), eqfunc, 0, 0, NULL }
	Static initialiser with a caller-chosen equality function.
#define	R_KV_PTR_ARRAY_INIT   R_KV_PTR_ARRAY_INIT_WITH_FUNC (NULL)
	Static initialiser with identity (pointer) equality.
#define	R_KV_PTR_ARRAY_INIT_STR   R_KV_PTR_ARRAY_INIT_WITH_FUNC (r_str_equal)
	Static initialiser for string-keyed arrays (uses r_str_equal).
#define	r_kv_ptr_array_init_str(array)   r_kv_ptr_array_init (array, r_str_equal)
	Convenience: initialise as a string-keyed array.
#define	r_kv_ptr_array_new()   r_kv_ptr_array_new_sized (0, NULL)
	Heap-allocate an empty identity-keyed array.
#define	r_kv_ptr_array_new_str()   r_kv_ptr_array_new_sized (0, r_str_equal)
	Heap-allocate an empty string-keyed array.
#define	r_kv_ptr_array_ref   r_ref_ref
	Increment the array's refcount.
#define	r_kv_ptr_array_unref   r_ref_unref
	Decrement the array's refcount; clears when it reaches zero.
#define	r_kv_ptr_array_size(array)   (array)->nsize
	Number of pairs currently in array.
#define	r_kv_ptr_array_alloc_size(array)   (array)->nalloc
	Allocated capacity (in pair slots).

Lookup and access
rpointer	r_kv_ptr_array_get_key (RKVPtrArray *array, rsize idx)
	Key at idx.
rpointer	r_kv_ptr_array_get_val (RKVPtrArray *array, rsize idx)
	Value at idx.
rpointer	r_kv_ptr_array_get (RKVPtrArray *array, rsize idx, rpointer *key)
	Return the value at idx and write the key into key.
rconstpointer	r_kv_ptr_array_get_const (const RKVPtrArray *array, rsize idx, rconstpointer *key)
	Const-correct variant of r_kv_ptr_array_get.
rsize	r_kv_ptr_array_find_range (const RKVPtrArray *array, rconstpointer key, rsize idx, rssize size)
	Find the first slot whose key matches key within [idx, idx+size).
#define	r_kv_ptr_array_find(array, key)   r_kv_ptr_array_find_range (array, key, 0, -1)
	Convenience: find the first slot whose key matches key.

Insertion and removal
rsize	r_kv_ptr_array_add (RKVPtrArray *array, rpointer key, RDestroyNotify keynotify, rpointer val, RDestroyNotify valnotify)
	Append a (key, value) pair with per-side destroy notifiers.
rsize	r_kv_ptr_array_update_idx (RKVPtrArray *array, rsize idx, rpointer key, RDestroyNotify keynotify, rpointer val, RDestroyNotify valnotify)
	Overwrite slot idx; previous key/value run through their destroy notifiers.
rsize	r_kv_ptr_array_remove_range (RKVPtrArray *array, rsize idx, rssize size)
	Stable range remove; destroy notifiers run on each entry.
rsize	r_kv_ptr_array_remove_key_first (RKVPtrArray *array, rpointer key)
	Remove the first slot whose key matches key.
rsize	r_kv_ptr_array_remove_key_all (RKVPtrArray *array, rpointer key)
	Remove every slot whose key matches key.
#define	r_kv_ptr_array_remove_idx(array, idx)   r_kv_ptr_array_remove_range (array, idx, 1)
	Convenience: stable single-slot remove.
#define	r_kv_ptr_array_remove_all(array)   r_kv_ptr_array_remove_range (array, 0, -1)
	Convenience: remove every pair.

Iteration
rsize	r_kv_ptr_array_foreach_range (RKVPtrArray *array, rsize idx, rssize size, RKeyValueFunc func, rpointer user)
	Invoke func on each pair in [idx, idx+size).
rsize	r_kv_ptr_array_foreach_const_range (const RKVPtrArray *array, rsize idx, rssize size, RKeyValueConstFunc func, rpointer user)
	Const-visitor variant of r_kv_ptr_array_foreach_range.
#define	r_kv_ptr_array_foreach(array, func, user)    r_kv_ptr_array_foreach_range (array, 0, -1, func, user)
	Convenience: iterate every pair.
#define	r_kv_ptr_array_foreach_const(array, func, user)    r_kv_ptr_array_foreach_const_range (array, 0, -1, func, user)
	Convenience: const-iterate every pair.

Detailed Description

Growable, refcounted ordered array of (key, value) pointer pairs.

Unlike Hash table, key order is preserved and lookups walk the array linearly via a caller-supplied REqualFunc. Useful when iteration order matters or the entry count is small enough that the constant-factor wins over hashing.

Function Documentation

r_kv_ptr_array_add()

rsize r_kv_ptr_array_add	(	RKVPtrArray *	array,
		rpointer	key,
		RDestroyNotify	keynotify,
		rpointer	val,
		RDestroyNotify	valnotify
	)

Append a (key, value) pair with per-side destroy notifiers.

Parameters

array	The array.
key	Key pointer.
keynotify	Destroy notifier for key, or NULL.
val	Value pointer.
valnotify	Destroy notifier for val, or NULL.

Returns

Index at which the pair was stored.

r_kv_ptr_array_foreach_const_range()

rsize r_kv_ptr_array_foreach_const_range	(	const RKVPtrArray *	array,
		rsize	idx,
		rssize	size,
		RKeyValueConstFunc	func,
		rpointer	user
	)

Const-visitor variant of r_kv_ptr_array_foreach_range.

Takes a const array and an RKeyValueConstFunc that receives rconstpointer key / value, so it can iterate without granting the callback mutable access to the stored pairs (the read-only mirror of get vs get_const).

r_kv_ptr_array_get()

rpointer r_kv_ptr_array_get	(	RKVPtrArray *	array,
		rsize	idx,
		rpointer *	key
	)

Return the value at idx and write the key into key.

Parameters

array	The array.
idx	Slot index.
key	Out: stored key (pass NULL to discard).

r_kv_ptr_array_init()

void r_kv_ptr_array_init	(	RKVPtrArray *	array,
		REqualFunc	eqfunc
	)

Initialise an embedded / stack array with the given equality function.

Parameters

array	The array.
eqfunc	Key comparator, or NULL for identity equality.