Vector API

Vector API definition. More...

Classes
struct	yavl_vec_t
	Type-agnostic vector definition. More...
struct	yavl_vec_errorable_t
	A return package which contains both result code and data. More...

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

Enumerations
enum	yavl_vec_res_t : char { YAVL_VEC_RES_OOM = -2 , YAVL_VEC_RES_NULL , YAVL_VEC_RES_OK = 0 , YAVL_VEC_RES_FAIL }
	Operation result codes. More...

Functions
yavl_vec_res_t	yavl_vec_init (yavl_vec_t *const memory, 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_push (yavl_vec_t *const vec, const void *const data)
	Pushes data to vector.
yavl_vec_errorable_t	yavl_vec_pop (yavl_vec_t *const vec)
	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_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_errorable_t	yavl_vec_ref (yavl_vec_t *const vec)
	Get reference to dynamic vector array.
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_flush (yavl_vec_t *const vec)
	Finalizes vector, to result it in statically-sized array. This allows you to drop vector metadata.

Detailed Description

Vector API definition.

Enumeration Type Documentation

yavl_vec_res_t

enum yavl_vec_res_t : char

Operation result codes.

Enumerator
YAVL_VEC_RES_OOM	Out-of-memory, allocator failures.
YAVL_VEC_RES_NULL	Null pointer exception.
YAVL_VEC_RES_OK	Operation success.
YAVL_VEC_RES_FAIL	Generic operation failure.

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_flush()

yavl_vec_errorable_t yavl_vec_flush

(

yavl_vec_t *const

vec

)

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.

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_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_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	memory,
		size_t	data_align,
		size_t	data_reserv )

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

Parameters

memory	An initialized memory space address to store metadata.
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

)

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

Parameters

vec	Fully initialized vector to pop from.

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 )

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.

Returns

Operation status.

yavl_vec_ref()

yavl_vec_errorable_t yavl_vec_ref

(

yavl_vec_t *const

vec

)

Get reference to dynamic vector array.

This is supposed to be used on-par with vec_chkptr for an adequate pointer safety.

Parameters

vec	Fully initialized vector.

Returns

Operation status.

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.