Vector API definition. More...

Classes
struct	yavl_vec_t
	Type-agnostic vector definition. More...

Macros
#define	YAVL_VEC_T_ALLOCATOR ((yavl_vec_t){})
	Allocator for yavl_vec_t.

Functions
yavl_vec_res_t	yavl_vec_init (yavl_vec_t *const vec, size_t data_align, size_t data_reserv)
	Initializes a new vector. Frees memory if it is already allocated.
yavl_vec_res_t	yavl_vec_fromarray (yavl_vec_t const vec, void const array, const size_t alignment, const size_t length)
	Converts given statically-sized array to the dynamic ones.
yavl_vec_res_t	yavl_vec_push (yavl_vec_t const vec, const void const data, const size_t num_el)
	Pushes data to vector.
yavl_vec_errorable_t	yavl_vec_pop (yavl_vec_t *const vec, const size_t num_el)
	Pops last elements out of vector. Doesn't free memory yet.
yavl_vec_res_t	yavl_vec_fit (yavl_vec_t *const vec)
	Resizes vector space to the current size.
yavl_vec_res_t	yavl_vec_scale (yavl_vec_t *const vec, size_t new_reservd)
	Resizes memory space to the given size.
yavl_vec_res_t	yavl_vec_set (yavl_vec_t const vec, size_t offset, const void const data)
	Sets offset -th element of vector to data.
yavl_vec_res_t	yavl_vec_get (yavl_vec_t const vec, size_t offset, void const out)
	Gets element at offset and stores it in out memory.
yavl_vec_res_t	yavl_vec_free (yavl_vec_t *const vec)
	Frees heap in vector and zeroes the entire object.
bool	yavl_vec_chkptr (const yavl_vec_t const vec, const void const ptr)
	Try to validate if the ptr pointer is in bounds of vec vector. This might be useful to ensure freshness of the ptr and protect it against out-of-memory-bounds scenarios.
yavl_vec_errorable_t	yavl_vec_toarray (yavl_vec_t const vec, size_t const final_len)
	Finalizes vector, to result it in statically-sized array. This allows you to drop vector metadata.

Detailed Description

Vector API definition.

Function Documentation

◆ yavl_vec_chkptr()

bool yavl_vec_chkptr	(	const yavl_vec_t *const	vec,
		const void *const	ptr )

Try to validate if the ptr pointer is in bounds of vec vector. This might be useful to ensure freshness of the ptr and protect it against out-of-memory-bounds scenarios.

This is additional safety measure. You should still manage your memory on your own for the most optimal case scenarios. NO GUARANTEES ARE MADE THIS WILL SOLVE EVERY OVERFLOW, BUG OR MEMORY-RELATED ISSUES and especially be aware of multi-thread software where a race condition between check and access might be happening (you might need to synchronize check and access between threads).

Parameters

vec	Fully initialized vector used for validation.
ptr	Pointer to validate.

Returns: Pointer correctness in regard to vector boundaries.

◆ yavl_vec_fit()

yavl_vec_res_t yavl_vec_fit ( yavl_vec_t *const vec )

Resizes vector space to the current size.

DO NOT USE when there's external pointer to data, as fit will free the data on vector it points to. YOU are expected to resolve conflicts like that yourself, e.g. simply by copying data out of vector.

There's also a way to test such pointer freshness on vector metadata, albeit it might require synchronization for multi-threaded logic to avoid race conditions.

Parameters

vec	Fully initialized vector.

Returns: Operation status (failures usually mean bad allocator, as data shrinking in practice should not cause OOM conditions).

◆ yavl_vec_free()

yavl_vec_res_t yavl_vec_free ( yavl_vec_t *const vec )

Frees heap in vector and zeroes the entire object.

Returns: Empty vector ready for initialization.

◆ yavl_vec_fromarray()

yavl_vec_res_t yavl_vec_fromarray	(	yavl_vec_t *const	vec,
		void *const	array,
		const size_t	alignment,
		const size_t	length )

Converts given statically-sized array to the dynamic ones.

The created vector is fully-fitted to the array, so it might be required to reserve more memory for it.

Parameters

vec	An allocated vector metadata memory space.
array	Array which should be transformed to a vector.
allignment	Array allignment, ex. sizeof(array[0])
length	Array length (size in allignment unit).

Returns: Pointer to array stored in heap. Needs to be freed via allocator at some point it becomes unnecesary or no longer accesible.

◆ yavl_vec_get()

yavl_vec_res_t yavl_vec_get	(	yavl_vec_t *const	vec,
		size_t	offset,
		void *const	out )

Gets element at offset and stores it in out memory.

Parameters

vec	Fully initialized vector.
offset	Place from which get vector element to store to out.
out	Memory pointer with same size as vector allignment.

Returns: Operation status.

◆ yavl_vec_init()

yavl_vec_res_t yavl_vec_init	(	yavl_vec_t *const	vec,
		size_t	data_align,
		size_t	data_reserv )

Initializes a new vector. Frees memory if it is already allocated.

Parameters

vec	An allocated vector metadata memory space.
data_align	A (maximum) size of element to store.
data_reserv	Default reservation to avoid frequent reallocations.

Returns: Operation status.

◆ yavl_vec_pop()

yavl_vec_errorable_t yavl_vec_pop	(	yavl_vec_t *const	vec,
		const size_t	num_el )

Pops last elements out of vector. Doesn't free memory yet.

Parameters

vec	Fully initialized vector to pop from.
num_el	Number of elements in vector to pop out as array.

Returns: Pointer of last element that was removed.

◆ yavl_vec_push()

yavl_vec_res_t yavl_vec_push	(	yavl_vec_t *const	vec,
		const void *const	data,
		const size_t	num_el )

Pushes data to vector.

Parameters

vec	Fully initialized vector to push to.
data	Pointer to data which should been pushed. Has to match data allignment.
num_el	Number of elements in data to push into vector.

Returns: Operation status.

◆ yavl_vec_scale()

yavl_vec_res_t yavl_vec_scale	(	yavl_vec_t *const	vec,
		size_t	new_reservd )

Resizes memory space to the given size.

DO NOT USE when there's external pointer to data, as scale in case of shrinking the memory might free the data on vector it points to. YOU are expected to resolve conflicts like that yourself, e.g. simply by copying data out of vector.

There's also a way to test such pointer freshness on vector metadata, albeit it might require synchronization for multi-threaded logic to avoid race conditions.

Parameters

vec	Fully initialized vector.
new_reservd	New memory space size to use for vector data, if smaller than length it will cut out data.

Returns: Operation status (OK/OOMs).

◆ yavl_vec_set()

yavl_vec_res_t yavl_vec_set	(	yavl_vec_t *const	vec,
		size_t	offset,
		const void *const	data )

Sets offset -th element of vector to data.

Parameters

vec	Fully initialized vector.
offset	Place in which write data to vector.
data	Memory pointer with same size as vector allignment.

Returns: Operation status.

◆ yavl_vec_toarray()

yavl_vec_errorable_t yavl_vec_toarray	(	yavl_vec_t *const	vec,
		size_t *const	final_len )

Finalizes vector, to result it in statically-sized array. This allows you to drop vector metadata.

Parameters

vec	Fully initialized vector, that will become correctly uninitialized.
final_len	Where to store logical array length, required.

Returns: Pointer to array stored in heap. Needs to be freed via allocator at some point it becomes unnecesary or no longer accesible.

Classes

Macros

Functions

Detailed Description

Function Documentation

◆ yavl_vec_chkptr()

◆ yavl_vec_fit()

◆ yavl_vec_free()

◆ yavl_vec_fromarray()

◆ yavl_vec_get()

◆ yavl_vec_init()

◆ yavl_vec_pop()

◆ yavl_vec_push()

◆ yavl_vec_scale()

◆ yavl_vec_set()

◆ yavl_vec_toarray()