rptrarray.h File Reference

Growable, refcounted array of rpointer values. More...

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

Go to the source code of this file.

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

Item access and search
#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.
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.

Inserting and updating
#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.
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.

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

Iteration and ordering
#define	r_ptr_array_foreach(array, func, user)   r_ptr_array_foreach_range (array, 0, -1, func, user)
	Convenience: invoke func on every item.
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.

Detailed Description

Growable, refcounted array of rpointer values.