Version 7.0
Copyright © 2021 Lowell D. Thomas
APG
… an ABNF Parser Generator
Data Structures | Functions
vector.h File Reference

Header file for the vector object - a dynamic array. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  vec_stats
 Vector usage statistics. 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 *vpVec, 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

Header file for the vector object - a dynamic array.

Definition in file vector.h.

Function Documentation

◆ bVecValidate()

abool bVecValidate ( void *  vpCtx)

Validates a vector component context.

Parameters
vpCtxPointer 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
vpCtxA 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
vpCtxA valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.
uiIndexThe 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
vpCtxA 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
vpMemPointer to a valid memory context, previously returned from vpMemCtor() If invalid, silently exits with a BAD_CONTEXT exit code.
uiElementSizeSize, in bytes, of each array element. Must be greater than 0.
uiInitialAllocNumber 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
vpCtxA 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
vpCtxA 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
vpCtxA 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
vpCtxA valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.
uiIndexIndex 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
vpCtxA valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.
uiCountThe 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
vpCtxA valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.
vpElementPointer 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
vpCtxA valid vector context pointer previously returned from vpVecCtor(). If invalid, silently exits with a BAD_CONTEXT exit code.
vpElementPointer to the first element to add. If NULL, space for the new elements is added but no data is copied to it.
uiCountThe 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
vpCtxA 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
vpCtxA 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
vpCtxA 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.

APG Version 7.0 is licensed under the 2-Clause BSD License,
an Open Source Initiative Approved License.