The Vector component API. More...

#include "Apg.h"
#include "Private.h"

Functions
void *	vpVecCtor (void *vpMemCtx, apg_uint uiElementSize, apg_uint uiInitialAlloc)

void	vVecDtor (void *vpCtx)

apg_uint	uiVecValidate (void *vpCtx)

apg_uint	uiVecBytes (void *vpCtx)

apg_uint	uiVecSize (void *vpCtx)

apg_uint	uiVecElementSize (void *vpCtx)

apg_uint	uiVecReallocations (void *vpCtx)

void	vVecClear (void *vpCtx)

void *	vpVecPush (void vpCtx, void vpElement)

void *	vpVecPushn (void vpCtx, void vpElement, apg_uint uiCount)

void *	vpVecPop (void *vpCtx)

void *	vpVecPopn (void *vpCtx, apg_uint uiCount)

void *	vpVecPopTo (void *vpCtx, apg_uint uiIndex)

void *	vpVecFront (void *vpCtx)

void *	vpVecBack (void *vpCtx)

void *	vpVecAt (void *vpCtx, apg_uint uiIndex)

Detailed Description

The Vector component API.

A Vector component is a dynamically dimensioned array. That is, the array will always grow large enough to accomodate newly added array elements. If the initial memory allocation becomes insufficient, the memory is re-allocated (and relocated). The memory size is never reduced. That is, the number of allocated array elements is always large enough to accomodate the maximum size of the component over its lifetime.

Warning: Because of dynamic data re-allocation, pointers to elements returned from the various APG functions are only valid until the next push or pop operation. Be careful to refresh pointers after any such operations.

See also: vpVecPush(); vpVecPushn(); vpVecPop(); vpVecPopn(); vpVecPopTo()

Definition in file Vector.c.

Function Documentation

◆ uiVecBytes()

apg_uint uiVecBytes ( void * vpCtx )

Gets the number of bytes of data in use.

Parameters

vpCtx a Vector component handle previously returned from vpVecCtor(). NULL or invalid handles are silently ignored.

See also: vpVecCtor()

Returns: the size in bytes of the data in use. May be smaller than the size of the allocation.

Definition at line 152 of file Vector.c.

◆ uiVecElementSize()

apg_uint uiVecElementSize ( void * vpCtx )

Gets the size of a single element.

Note that:
uiVecBytes() = uiVecElementSize() * uiVecSize().

Parameters

vpCtx a Vector component handle previously returned from vpVecCtor(). NULL or invalid handles are silently ignored.

See also: vpVecCtor()

Returns: the number of bytes in a single element.

Definition at line 185 of file Vector.c.

◆ uiVecReallocations()

apg_uint uiVecReallocations ( void * vpCtx )

Gets the number times the array memory has been reallocated.

Parameters

vpCtx a Vector component handle previously returned from vpVecCtor().

See also: vpVecCtor()

Returns: the number times the array memory has been reallocated.

Definition at line 200 of file Vector.c.

◆ uiVecSize()

apg_uint uiVecSize ( void * vpCtx )

Gets the number of array elements in use.

Parameters

vpCtx a Vector component handle previously returned from vpVecCtor(). NULL or invalid handles are silently ignored.

See also: vpVecCtor()

Returns: the number of vector array elements in use. May be smaller than the number that have been allocated.

Definition at line 167 of file Vector.c.

◆ uiVecValidate()

apg_uint uiVecValidate ( void * vpCtx )

Validates a Vector component handle.

Parameters

vpCtx a Vector component handle previously returned from vpVecCtor(). NULL or invalid handles are silently ignored.

See also: vpVecCtor()

Returns: true if the handle is valid, false otherwise.

Definition at line 142 of file Vector.c.

◆ vpVecAt()

void* vpVecAt	(	void *	vpCtx,
		apg_uint	uiIndex
	)

Get a the indexed element in the array. The array is not altered.

Parameters

vpCtx	a Vector component handle previously returned from vpVecCtor().
uiIndex	the index of the element to get (0-based)

See also: vpVecCtor()

Returns: a pointer to the indexed element in the array. NULL if the array is empty or the index is out of range.

Definition at line 433 of file Vector.c.

◆ vpVecBack()

void* vpVecBack ( void * vpCtx )

Get a the last element in the array. The array is not altered.

Parameters

vpCtx a Vector component handle previously returned from vpVecCtor().

See also: vpVecCtor()

Returns: a pointer to the last element in the array. NULL if the array is empty.

Definition at line 414 of file Vector.c.

◆ vpVecCtor()

void* vpVecCtor	(	void *	vpMemCtx,
		apg_uint	uiElementSize,
		apg_uint	uiInitialAlloc
	)

The Vector comonent constructor.

Parameters

vpMemCtx	a Memory component context handle, previously returned from vpMemCtor().
uiElementSize	size, in bytes, of each array element. If 0, uses the default element size APG_VEC_ELEMENT.
uiInitialAlloc	number of elements to initially allocate. If 0, uses the default APG_VEC_ALLOC.

See also: vpMemCtor()

Returns: a Vector component context handle (a void pointer to an opaque data struct.) NULL on construction failure.

Definition at line 81 of file Vector.c.

◆ vpVecFront()

void* vpVecFront ( void * vpCtx )

Get a the first element in the array. The array is not altered.

Parameters

vpCtx a Vector component handle previously returned from vpVecCtor().

See also: vpVecCtor()

Returns: a pointer to the first element in the array. NULL if the array is empty.

Definition at line 396 of file Vector.c.

◆ vpVecPop()

void* vpVecPop ( void * vpCtx )

Pops one element from the end of the array.

Parameters

vpCtx a Vector component handle previously returned from vpVecCtor().

See also: vpVecCtor(); vpVecPopn(); vpVecPopTo(); vpVecPush(); vpVecPushn()

Returns: a pointer to the popped element. NULL if the Vector is empty.

Definition at line 315 of file Vector.c.

◆ vpVecPopn()

void* vpVecPopn	(	void *	vpCtx,
		apg_uint	uiCount
	)

Pops one or more elements from the end of the array.

Parameters

vpCtx	a Vector component handle previously returned from vpVecCtor().
uiCount	the number of elements to pop.

See also: vpVecCtor(); vpVecPop(); vpVecPopTo(); vpVecPush(); vpVecPushn()

Returns: a pointer to the first popped element. NULL if the Vector is empty.

Definition at line 341 of file Vector.c.

◆ vpVecPopTo()

void* vpVecPopTo	(	void *	vpCtx,
		apg_uint	uiIndex
	)

Pops one or more elements from the end of the array.

Parameters

vpCtx	a Vector component handle previously returned from vpVecCtor().
uiIndex	index of the first element to pop. Elements uiIndex and all higher indexed elements are popped.

See also: vpVecCtor(); vpVecPop(); vpVecPopn(); vpVecPush(); vpVecPushn()

Returns: a pointer to the first popped element. NULL if the Vector is empty or if uiIndex is larger than the largest indexed element in the array.

Definition at line 376 of file Vector.c.

◆ vpVecPush()

void* vpVecPush	(	void *	vpCtx,
		void *	vpElement
	)

Adds one element to the end of the array.

Parameters

vpCtx	a Vector component handle previously returned from vpVecCtor().
vpElement	pointer to the element to add. If NULL, space for a new element is added but no data is copied to it.

See also: vpVecCtor(); vpVecPushn(); vpVecPop(); vpVecPopn(); vpVecPopTo()

Returns: a pointer to the new element in the array. NULL on failure.

Definition at line 238 of file Vector.c.

◆ vpVecPushn()

void* vpVecPushn	(	void *	vpCtx,
		void *	vpElement,
		apg_uint	uiCount
	)

Adds one or more elements to the end of the array.

Parameters

vpCtx	a Vector component handle previously returned from vpVecCtor().
vpElement	pointer to the first element to add. If NULL, space for the new elements is added but no data is copied to it.
uiCount	the number of elements to add.

See also: vpVecCtor(); vpVecPush(); vpVecPop(); vpVecPopn(); vpVecPopTo()

Returns: a pointer to the first new element in the array. NULL on failure.

Definition at line 276 of file Vector.c.

◆ vVecClear()

void vVecClear ( void * vpCtx )

Clears all used elements in a Vector component.

This simply resents the current element pointer to zero. No data is actually deleted. No memory is released or re-allocated.

Parameters

vpCtx a Vector component handle previously returned from vpVecCtor(). NULL or invalid handles are silently ignored.

See also: vpVecCtor()

Definition at line 218 of file Vector.c.

◆ vVecDtor()

void vVecDtor ( void * vpCtx )

The Vector component destructor. Frees all resouces allocated to this component.

Parameters

vpCtx a Vector component handle previously returned from vpVecCtor(). NULL or invalid handles are silently ignored.

See also: vpVecCtor()

Definition at line 123 of file Vector.c.

Functions

Detailed Description

Function Documentation

◆ uiVecBytes()

◆ uiVecElementSize()

◆ uiVecReallocations()

◆ uiVecSize()

◆ uiVecValidate()

◆ vpVecAt()

◆ vpVecBack()

◆ vpVecCtor()

◆ vpVecFront()

◆ vpVecPop()

◆ vpVecPopn()

◆ vpVecPopTo()

◆ vpVecPush()

◆ vpVecPushn()

◆ vVecClear()

◆ vVecDtor()