rkvptrarray.h File Reference

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

#include <rlib/rtypes.h>
#include <rlib/rref.h>
#include <rlib/data/rhashfuncs.h>

Go to the source code of this file.

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
#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).
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.

Lookup and access
#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.
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).

Insertion and removal
#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.
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.

Iteration
#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.
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.

Detailed Description

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