vt_t 7 2016-02-28 genvector manual

NAME

vt_t - vector types

SYNPOSIS

vt_t - the vector type

vt_size_t - integral type that represents lengths and indices

vt_elem_t - type of each element in the vector

DESCRIPTION

Genvector(7) is a type-independent dynamic array engine. It is instantiated to create different vector types and code that service the given vector type. The most important parameters the that are determined during the instantiation are the following three types.

vt_t is the main vector type. vt_t is the naming convention in the documentation only. In practice it has a longer, type and initialization specific name, such as vti0_t for "a vector of integers where new elements are initialized to 0".

The actual name of vt_t is automatically determined using instantiation parameter GVT(). The universal name of vt_t is GVTTYPE in the source.

vt_t is a struct that has the following non-optional fields (the caller may access these):
vt_size_t used The actual length of the vector (number of slots used by active elements). When used is 0, the vector is empty. If a vector is terminated (see vt_term(7)), the array is always allocated between vt_init and vt_uninit, and the terminator present, even if used is 0. For non-terminated vectors, when used is 0, the array field is free'd and set to NULL.
vt_size_t alloced Slots already allocated; when new elements are added, the array is reallocated in chunks for efficiency. Alloced is always bigger or equal to used. For terminated vectors (see vt_term(7)), alloced is always at least 1 slot larger than used, because the terminator element is placed at [used].
vt_elem_t *array The actual array of elements. For unterminated arrays, it is NULL when used is 0. Always NULL after vt_uninit.
It may also feature the follogin optional fields, depending on the instantiation-configuration:
void (*init_elem)(GVTTYPE *vect, GVT_ELEM_TYPE *elem) User callback to initialize new elements (see vt_init_elem(7))
int (*elem_constructor)(GVTTYPE *vect, GVT_ELEM_TYPE *elem); User provided element constructor (see vt_construction(7))
void (*elem_destructor)(GVTTYPE *vect, GVT_ELEM_TYPE *elem); User provided element destructor (see vt_construction(7))
int (*elem_copy)(GVTTYPE *dst_vect, GVT_ELEM_TYPE *dst, GVT_ELEM_TYPE *src) User provided element (deep) copy (see vt_construction(7))
GVT_USER_FIELDS Custom user defined fields of various type (see vt_user_fields(7))

vt_size_t is an unsigned integral type used to represent vector length, indices and sizes. Unit is always number of elements instead of number of bytes. This makes it possible to choose vt_size_t to something narrow, such as unsigned short int, for smaller vector types. The universal name of vt_size_t is GVT_SIZE_TYPE in the source.

vt_elem_t is the actual element type the vector array is built of. This may be anything from a char to large structures. However, it must be a fixed type with a fixed size: vector is a dynamic array of uniform sized elements. All relevant vector operations (set, append) are provided in two variants: one that takes an element pointer and one that takes an element. For large elements the former is more efficient while for small elements the latter is faster. The universal name of vt_size_t is GVT_ELEM_TYPE in the source.

SEE ALSO

vt_t 7 2016-02-28 genvector manual