The vector object. Provides a dynamic memory array. More...

#include "./lib.h"

Include dependency graph for vector.c:

Data Structures
struct	vector
	Private for internal use only. Defines the vector's state. Opaque to applications. More...

Macros
Statistics Collection Macros used by the vector object.
If APG_VEC_STATS is defined, these 3 macros will be defined to call the statistics gathering functions. If APG_VEC_STATS is not defined, these macros generate no code.
#define	STATS_PUSH(s, p) vStatsPush((s), (p))
	Called by the vector object to count the number of pushed (added) elements. More...

#define	STATS_POP(s, p) vStatsPop((s), (p))
	Called by the vector object to count the number of popped (removed) elements. More...

#define	STATS_GROW(s, n) vStatsGrow((s), (n))
	Called by the vector object to count the number of times the size of the vector was automatically extended. More...

Functions
void *	vpVecCtor (void *vpMem, aint uiElementSize, aint uiInitialAlloc)
	The vector object constructor. More...

void	vVecDtor (void *vpCtx)
	The vector component destructor. More...

abool	bVecValidate (void *vpCtx)
	Validates a vector component context. More...

void *	vpVecPush (void vpCtx, void vpElement)
	Adds one element to the end of the array. More...

void *	vpVecPushn (void vpCtx, void vpElement, aint uiCount)
	Adds one or more elements to the end of the array. More...

void *	vpVecPop (void *vpCtx)
	Pops one element from the end of the array. More...

void *	vpVecPopn (void *vpCtx, aint uiCount)
	Pops one or more elements from the end of the array. More...

void *	vpVecPopi (void *vpCtx, aint uiIndex)
	Pops the element at the given zero-based index and all higher indexes. More...

void *	vpVecFirst (void *vpCtx)
	Get the first element one the vector. The vector is not altered. More...

void *	vpVecLast (void *vpCtx)
	Get the last element one the vector. The vector is not altered. More...

void *	vpVecAt (void *vpCtx, aint uiIndex)
	Get a the indexed vector element. The vector is not altered. More...

aint	uiVecLen (void *vpCtx)
	Get the vector length. That is, the number of elements on the vector. More...

void *	vpVecBuffer (void *vpCtx)
	Get a pointer to the vector buffer. More...

void	vVecClear (void *vpCtx)
	Clears all used elements in a vector component. More...

void	vVecStats (void vpCtx, vec_stats spStats)

Detailed Description

The vector object. Provides a dynamic memory array.

This suite of member functions provides tools for managing a dynamic array of arbitrary-sized data elements. It is based on a last-in-first-out (LIFO), push/pop, stack model with additional element access operations.

CAVEAT: Care must be taken when using data pointers returned from the member functions. It must always be assumed that they are only valid until the next member function call. If a data location needs to be retained as application state data, save its vector element index as the state data and convert it to a pointer (vpVecAt() or similar location techniques) only when needed.

Definition in file vector.c.

Macro Definition Documentation

◆ STATS_GROW

#define STATS_GROW	(	s,
		n
	)	vStatsGrow((s), (n))

Called by the vector object to count the number of times the size of the vector was automatically extended.

Definition at line 85 of file vector.c.

◆ STATS_POP

#define STATS_POP	(	s,
		p
	)	vStatsPop((s), (p))

Called by the vector object to count the number of popped (removed) elements.

Definition at line 81 of file vector.c.

◆ STATS_PUSH

#define STATS_PUSH	(	s,
		p
	)	vStatsPush((s), (p))

Called by the vector object to count the number of pushed (added) elements.

Definition at line 77 of file vector.c.

Function Documentation

◆ bVecValidate()

abool bVecValidate ( void * vpCtx )

Validates a vector component context.

Parameters

vpCtx Pointer to vector context.

Returns: True if the context is valid, false otherwise.

Definition at line 179 of file vector.c.

◆ uiVecLen()

aint uiVecLen ( void * vpCtx )

Get the vector length. That is, the number of elements on the vector.

Parameters

vpCtx A valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.

Returns: The number of elements currently in the vector.

Definition at line 385 of file vector.c.

◆ vpVecAt()

void* vpVecAt	(	void *	vpCtx,
		aint	uiIndex
	)

Get a the indexed vector element. The vector is not altered.

Parameters

vpCtx	A valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.
uiIndex	The index of the element to get (0-based).

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 362 of file vector.c.

◆ vpVecBuffer()

void* vpVecBuffer ( void * vpCtx )

Get a pointer to the vector buffer.

This is different from vpVecFirst() in that it will always point to the buffer even if there are no elements currently in it.

Parameters

vpCtx A valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.

Returns: Pointer beginning of the current buffer

Definition at line 402 of file vector.c.

◆ vpVecCtor()

void* vpVecCtor	(	void *	vpMem,
		aint	uiElementSize,
		aint	uiInitialAlloc
	)

The vector object constructor.

The vector object is one of the few APG objects that does not require an exception pointer for construction. Rather it takes a memory object pointer. The memory object is the vector's parent. All memory allocations are done with the parent object and all exceptions are reported on the parent's exception object. Calling the parent memory object's destructor will free all memory associated with this vector object.

Parameters

vpMem	Pointer to a valid memory context, previously returned from vpMemCtor() If invalid, silently exits with a BAD_CONTEXT exit code.
uiElementSize	Size, in bytes, of each array element. Must be greater than 0.
uiInitialAlloc	Number of elements to initially allocate. Must be greater than 0.

Returns: Returns a vector context pointer. Throws exception on input or memory allocation error.

Definition at line 118 of file vector.c.

◆ vpVecFirst()

void* vpVecFirst ( void * vpCtx )

Get the first element one the vector. The vector is not altered.

Parameters

vpCtx A valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.

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

Definition at line 326 of file vector.c.

◆ vpVecLast()

void* vpVecLast ( void * vpCtx )

Get the last element one the vector. The vector is not altered.

Parameters

vpCtx A valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.

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

Definition at line 343 of file vector.c.

◆ vpVecPop()

void* vpVecPop ( void * vpCtx )

Pops one element from the end of the array.

Parameters

vpCtx A valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.

Returns: A pointer to the popped element. NULL if the vector is empty. NOTE: the popped element data remains valid until the next call to vpVecPush() or vpVecPushn();

Definition at line 250 of file vector.c.

◆ vpVecPopi()

void* vpVecPopi	(	void *	vpCtx,
		aint	uiIndex
	)

Pops the element at the given zero-based index and all higher indexes.

Parameters

vpCtx	A valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.
uiIndex	Index of the first element to pop. Element uiIndex and all higher indexed elements are popped.

Returns

A pointer to the first popped element, the element with index uiIndex. NULL if the vector is empty or no elements are popped. i.e. if uiIndex is >= uiVecLen(vpCtx). NOTE: the popped element data remains valid until the next call to vpVecPush() or vpVecPushn().
Example: A common usage is to restore a vector to its previous state. Suppose a vector, ctx, has 10 elements.

uiCount = uiVecLen(ctx);           // uiCount = 10, the number of elements on the vector
vpNew = vpVecPushn(ctx, NULL, 5);  // vpNew points to element 11 (index 10), there are now 15 elements on the vector
vpOld = vpVecPopi(ctx, uiCount);   // vpOld now points to the popped element 11 (index = 10) and the vector is restored to its previous condition

Definition at line 306 of file vector.c.

◆ vpVecPopn()

void* vpVecPopn	(	void *	vpCtx,
		aint	uiCount
	)

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

Parameters

vpCtx	A valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.
uiCount	The number of elements to pop. If uiCount > number of elements, all remaining elements are popped.

Returns: A pointer to the first (lowest index) popped element. NULL if the vector is empty or uiCount == 0. NOTE: the popped element data remains valid until the next call to vpVecPush() or vpVecPushn();

Definition at line 271 of file vector.c.

◆ vpVecPush()

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

Adds one element to the end of the array.

Parameters

vpCtx	A valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.
vpElement	Pointer to the element to add. If NULL, space for a new element is added but no data is copied to it.

Returns: A pointer to the new element in the array. Exception thrown on memory allocation error, if any.

Definition at line 193 of file vector.c.

◆ vpVecPushn()

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

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

Parameters

vpCtx	A valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.
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.

Returns: A pointer to the new element in the array. Exception thrown if uiCount = 0 or on memory allocation failure.

Definition at line 221 of file vector.c.

◆ vVecClear()

void vVecClear ( void * vpCtx )

Clears all used elements in a vector component.

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

Parameters

vpCtx A valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code. If NULL, the call is silently ignored. However, if non-NULL it must be a valid context pointer.

Definition at line 420 of file vector.c.

◆ vVecDtor()

void vVecDtor ( void * vpCtx )

The vector component destructor.

Frees all memory allocated to this vector object.

Note that all memory is also freed when the parent memory object is destroyed.

Parameters

vpCtx A vector context pointer previously returned from vpVecCtor(). Silently ignores NULL. However, if non-NULL must be valid or the application will exit with a BAD_CONTEXT exit code.

Definition at line 161 of file vector.c.

◆ vVecStats()

void vVecStats	(	void *	vpCtx,
		vec_stats *	spStats
	)

Copy the vector statistics in the user's buffer.

Note that APG_VEC_STATS must be defined for statistics collection. If not defined, this function will return an empty vec_stats structure.

Parameters

vpCtx	A valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.
spStats	- pointer to the user's stats buffer

Definition at line 459 of file vector.c.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ STATS_GROW

◆ STATS_POP

◆ STATS_PUSH

Function Documentation

◆ bVecValidate()

◆ uiVecLen()

◆ vpVecAt()

◆ vpVecBuffer()

◆ vpVecCtor()

◆ vpVecFirst()

◆ vpVecLast()

◆ vpVecPop()

◆ vpVecPopi()

◆ vpVecPopn()

◆ vpVecPush()

◆ vpVecPushn()

◆ vVecClear()

◆ vVecDtor()

◆ vVecStats()