Pointer array

Growable, refcounted array of rpointer values with optional per-slot destroy notifiers. More...

Files
file	rptrarray.h
	Growable, refcounted array of rpointer values.

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

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

Lifecycle
void	r_ptr_array_init (RPtrArray *array)
	Initialise an embedded / stack RPtrArray to empty.
void	r_ptr_array_clear (RPtrArray *array)
	Drop every item and release backing storage; destroy notifiers run.
RPtrArray *	r_ptr_array_new_sized (rsize size)
	Heap-allocate an array with a preset initial capacity.
#define	R_PTR_ARRAY_INIT   { R_REF_STATIC_INIT (NULL), 0, 0, NULL }
	Static initialiser for an embedded / stack RPtrArray.
#define	r_ptr_array_new()   r_ptr_array_new_sized (0)
	Heap-allocate an empty array (initial capacity 0).
#define	r_ptr_array_ref   r_ref_ref
	Increment the array's refcount.
#define	r_ptr_array_unref   r_ref_unref
	Decrement the array's refcount; clears when it reaches zero.
#define	r_ptr_array_size(array)   (array)->nsize
	Number of items currently in array.
#define	r_ptr_array_alloc_size(array)   (array)->nalloc
	Allocated capacity (in slots).

Item access and search
rpointer	r_ptr_array_get (RPtrArray *array, rsize idx)
	Return the pointer stored at idx.
rconstpointer	r_ptr_array_get_const (const RPtrArray *array, rsize idx)
	Const-correct variant of r_ptr_array_get.
rsize	r_ptr_array_find_range (RPtrArray *array, rpointer data, rsize idx, rssize size)
	Find first occurrence of data within the range starting at idx for size items.
#define	r_ptr_array_find(array, data)   r_ptr_array_find_range (array, data, 0, -1)
	Convenience: find first occurrence of data over the whole array.

Inserting and updating
rsize	r_ptr_array_add (RPtrArray *array, rpointer data, RDestroyNotify notify)
	Append data to the array.
rsize	r_ptr_array_insert (RPtrArray *array, rsize idx, rpointer data, RDestroyNotify notify)
	Insert data at idx, shifting later items up by one.
rsize	r_ptr_array_update_idx (RPtrArray *array, rsize idx, rpointer data, RDestroyNotify notify)
	Overwrite the slot at idx.
rsize	r_ptr_array_clear_range (RPtrArray *array, rsize idx, rssize size)
	Write NULL into every slot in the range; previous values run through their destroy notifiers.
#define	r_ptr_array_clear_idx(array, idx)   r_ptr_array_update_idx (array, idx, NULL, NULL)
	Convenience: write NULL into slot idx, freeing the previous value.

Removal — three semantics
_full variants accept a (func, user) pair that's invoked on each removed item; the macro shortcuts pass (NULL, NULL). idx family — stable: removes the slot and shifts later items down. O(n). idx_fast family — swap-with-last into the gap. O(1) but reorders items. idx_clear family — overwrite the slot with NULL without shrinking nsize. O(1).
rsize	r_ptr_array_remove_idx_full (RPtrArray *array, rsize idx, RFunc func, rpointer user)
	Stable remove of slot idx; func runs on the displaced item.
rsize	r_ptr_array_remove_idx_fast_full (RPtrArray *array, rsize idx, RFunc func, rpointer user)
	Swap-with-last remove of slot idx; func runs on the displaced item.
rsize	r_ptr_array_remove_idx_clear_full (RPtrArray *array, rsize idx, RFunc func, rpointer user)
	Clear-in-place at slot idx; func runs on the displaced item.
rsize	r_ptr_array_remove_range_full (RPtrArray *array, rsize idx, rssize size, RFunc func, rpointer user)
	Stable range remove with per-item function.
rsize	r_ptr_array_remove_range_fast_full (RPtrArray *array, rsize idx, rssize size, RFunc func, rpointer user)
	Swap-with-last range remove with per-item function.
rsize	r_ptr_array_remove_range_clear_full (RPtrArray *array, rsize idx, rssize size, RFunc func, rpointer user)
	Clear-in-place over the range with per-item function.
#define	r_ptr_array_remove_all(array)   r_ptr_array_remove_range_clear_full (array, 0, -1, NULL, NULL)
	Convenience: remove all items, no per-item function.
#define	r_ptr_array_remove_all_full(array, func, user)   r_ptr_array_remove_range_clear_full (array, 0, -1, func, user)
	Convenience: remove all items, calling func on each.
#define	r_ptr_array_remove_idx(array, idx)   r_ptr_array_remove_idx_full (array, idx, NULL, NULL)
	Convenience: stable remove of slot idx, no per-item function.
#define	r_ptr_array_remove_idx_fast(array, idx)   r_ptr_array_remove_idx_fast_full (array, idx, NULL, NULL)
	Convenience: swap-with-last remove of slot idx, no per-item function.
#define	r_ptr_array_remove_idx_clear(array, idx)   r_ptr_array_remove_idx_clear_full (array, idx, NULL, NULL)
	Convenience: clear-in-place at slot idx, no per-item function.
#define	r_ptr_array_remove_first_full(array, data, func, user)   r_ptr_array_remove_idx_full (array, r_ptr_array_find (array, data), func, user)
	Convenience: stable remove of first occurrence of data.
#define	r_ptr_array_remove_first_fast_full(array, data, func, user)   r_ptr_array_remove_idx_fast_full (array, r_ptr_array_find (array, data), func, user)
	Convenience: swap-with-last remove of first occurrence of data.
#define	r_ptr_array_remove_first_clear_full(array, data, func, user)   r_ptr_array_remove_idx_clear_full (array, r_ptr_array_find (array, data), func, user)
	Convenience: clear-in-place at first occurrence of data.
#define	r_ptr_array_remove_first(array, data)   r_ptr_array_remove_first_full (array, data, NULL, NULL)
	Convenience: stable remove of data, no per-item function.
#define	r_ptr_array_remove_first_fast(array, data)   r_ptr_array_remove_first_fast_full (array, data, NULL, NULL)
	Convenience: swap-with-last remove of data, no per-item function.
#define	r_ptr_array_remove_first_clear(array, data)   r_ptr_array_remove_first_clear_full (array, data, NULL, NULL)
	Convenience: clear-in-place at data, no per-item function.
#define	r_ptr_array_remove_range(array, idx, inc)   r_ptr_array_remove_range_full (array, idx, inc, NULL, NULL)
	Convenience: stable range remove, no per-item function.
#define	r_ptr_array_remove_range_fast(array, idx, inc)   r_ptr_array_remove_range_fast_full (array, idx, inc, NULL, NULL)
	Convenience: swap-with-last range remove.
#define	r_ptr_array_remove_range_clear(array, idx, inc)   r_ptr_array_remove_range_clear_full (array, idx, inc, NULL, NULL)
	Convenience: clear-in-place over the range.

Iteration and ordering
rsize	r_ptr_array_foreach_range (RPtrArray *array, rsize idx, rssize size, RFunc func, rpointer user)
	Invoke func on each item in the range [idx, idx+size).
void	r_ptr_array_sort (RPtrArray *array, RCmpFunc cmp)
	In-place sort using comparator cmp.
#define	r_ptr_array_foreach(array, func, user)   r_ptr_array_foreach_range (array, 0, -1, func, user)
	Convenience: invoke func on every item.

Detailed Description

Growable, refcounted array of rpointer values with optional per-slot destroy notifiers.

Use either as a heap-allocated refcounted object (r_ptr_array_new) or as an embedded / stack value (R_PTR_ARRAY_INIT + r_ptr_array_init). Removals support three semantics: stable in-order (remove_idx), swap-last-into-the-gap (remove_idx_fast), and zero-the-slot without shrinking (remove_idx_clear). Each shape has a _full variant that fires a caller-supplied function on the displaced item.

Function Documentation

r_ptr_array_add()

rsize r_ptr_array_add	(	RPtrArray *	array,
		rpointer	data,
		RDestroyNotify	notify
	)

Append data to the array.

Parameters

array	The array.
data	Pointer to store.
notify	Destroy notifier invoked when the slot is later cleared / removed, or NULL.

Returns

Index at which data was stored.

r_ptr_array_find_range()

rsize r_ptr_array_find_range	(	RPtrArray *	array,
		rpointer	data,
		rsize	idx,
		rssize	size
	)

Find first occurrence of data within the range starting at idx for size items.

Parameters

array	The array.
data	Value to match (identity comparison).
idx	First index to search.
size	Range length, or -1 for "to end".

Returns

Index of the first match, or R_PTR_ARRAY_INVALID_IDX.

r_ptr_array_update_idx()

rsize r_ptr_array_update_idx	(	RPtrArray *	array,
		rsize	idx,
		rpointer	data,
		RDestroyNotify	notify
	)

Overwrite the slot at idx.

The previous slot's destroy notifier runs (if any) before data takes its place.