Header file for the vector object - a dynamic array.
More...
Go to the source code of this file.
|
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) |
|
Header file for the vector object - a dynamic array.
Definition in file vector.h.
◆ 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.
APG Version 7.0 is licensed under the
2-Clause BSD License,
an Open Source Initiative Approved License.