genvector 7	2016-02-29	genvector manual

NAME

genvector - generic vectors (gynamic arrays and dynamic strings)

DESCRIPTION

Genvector is a type-independent dynamic array engine. The generic engine is instantiated by wrappers to implement specific vector types. User application normally includes and links the wrappers. All symbol names created by an instantiation are prefixed with an instant-specific word (see wrapper naming conventions).
For example if the application needs a dynamic array (vector) of integers, it includes the standard vector instance "vti0.h" and links to genvectors.a (that in turn contains vti0.o); see example int0. If then application needs to build a vector of a custom type, e.g. a struct, it creates a vector instance for that type; see example struct0.
Genvector provides an array of uniform elements. The array is reallocated to grow and shrink as caller adds elements or truncates the vector. There are different, wrapper-configured options to initialize and/or uninitialize elements.
A common use case is char * (or wchar_t *) arrays, which are called "dynamic strings" and are prefixed with gds_ or wgds_ in the standard instances.

Wrapper naming conventions
The most important thing a wrapper configures is the symbol prefix for the instance. While wrappers are free to choose arbitrary prefixes, there are conventions the standard distribution follows. There are two set of standard prefixes.
Character based vectors (strings) are gds_ (for char) and wgds_ (for wchar_t). I.e. the vector type that is called vt_t in the docuemtnation is gds_t and wgds_t and the function appending a character (vt_append() in the documentation) is called gds_append() and wgds_append() respectively.
Generic array types are named as vt** where the first * refers to the type and the second * refers to the element initialization strategy. Types are: "i" for "int". Initialization is "0" for initializing all new elements to 0, "i" for user provided initialization function and "o" for object initialization (constructor, desrtuctor, copy functions). For example hti0_t (and hti0_append()) refers to an integer vector whose new elements are initialized to 0.
Calls
Once the generic engine is instantiated into a type- and configuration-specific instance, there are a number of functions the user can call. The actual function names are not prefixed with vt_ as in the documentation, but an instance specific prefix, see above.

vt_init(3) Initialize a vector.
vt_uninit(3) Destroy a vector.
vt_len(3) Return the length (number of active elements, aka. the used field) of the vector.
vt_in_bound(3) Returns whether the given index exists in the vector.
vt_get(3) Return pointer to an element, by index.
vt_set(3) Overwrite an element, by index (the new content passed on stack).
vt_set_ptr(3) Overwrite an element, by index (a pointer to the new content passed).
vt_resize(3) Low level allocation adjust call (normally not called from an application).
vt_truncate(3) Make a vector smaller.
vt_enlarge(3) Make a vector larger.
vt_alloc_append(3) Allocate new, initialized/constructed elements at the end of the vector, return a pointer to the first new element.
vt_append(3) Append an element at the end of the vector (content passed on stack).
vt_append_len(3) Append an element or a raw array of elements at the end of the vector (content passed by pointer and number-of-elements).
vt_concat(3) Append a vector at the end of another vectory copying all elements.
vt_copy(3) Copy elements between vectors or within a vector.
vt_remove(3) Remove elements from an array, moving remaining elements to fill in the gap; forward addressing version.
vt_remove_bw(3) Remove elements from an array, moving remaining elements to fill in the gap; backward addressing version.
vt_append_array(3) Same as vt_append_len(3), except try to determine length of the source raw array by finding a terminator (works with terminated vectors only).

Configuration choices
The wrapper that instantiates the engine needs to make certain mandatory configuration choices and may make a few optional choices. These are macros that need to be #defined before including the engine. The macros are automatically undefined by the engine so that the user application can include multiple different wrapper headers without macro name collision.
A complete list of features can be found in hti0.h with the documentation in accompanying comments.

vt_init(3)	Initialize a vector.
vt_uninit(3)	Destroy a vector.
vt_len(3)	Return the length (number of active elements, aka. the used field) of the vector.
vt_in_bound(3)	Returns whether the given index exists in the vector.
vt_get(3)	Return pointer to an element, by index.
vt_set(3)	Overwrite an element, by index (the new content passed on stack).
vt_set_ptr(3)	Overwrite an element, by index (a pointer to the new content passed).
vt_resize(3)	Low level allocation adjust call (normally not called from an application).
vt_truncate(3)	Make a vector smaller.
vt_enlarge(3)	Make a vector larger.
vt_alloc_append(3)	Allocate new, initialized/constructed elements at the end of the vector, return a pointer to the first new element.
vt_append(3)	Append an element at the end of the vector (content passed on stack).
vt_append_len(3)	Append an element or a raw array of elements at the end of the vector (content passed by pointer and number-of-elements).
vt_concat(3)	Append a vector at the end of another vectory copying all elements.
vt_copy(3)	Copy elements between vectors or within a vector.
vt_remove(3)	Remove elements from an array, moving remaining elements to fill in the gap; forward addressing version.
vt_remove_bw(3)	Remove elements from an array, moving remaining elements to fill in the gap; backward addressing version.
vt_append_array(3)	Same as vt_append_len(3), except try to determine length of the source raw array by finding a terminator (works with terminated vectors only).

NAME

DESCRIPTION

Wrapper naming conventions

Calls

Configuration choices

SEE ALSO