---

ds_vector.h File Reference

#include "ds_common.h"

Go to the source code of this file.

Data Structures
struct	Vector
Defines
#define	VecOffset(vec, iter)   (iter - vec->ppData)
#define	VecIter(vec, index)   (vec->ppData + index)
Functions
Vector *	VectorCreate (long lSize, long lDelta)
void	VectorDestroy (Vector *pVec)
void **	VectorPushBack (Vector *pVec, void *pData)
void **	VectorPushFront (Vector *pVec, void *pData)
void **	VectorFind (Vector *pVec, void **ppIter, void *pData, bool bDirection)
void **	VectorSimpleFind (Vector *pVec, void *pData)
void	VectorRemove (Vector *pVec, void **pIter)
void	VectorPopBack (Vector *pVec)
void	VectorPopFront (Vector *pVec)
Variables
Vector	Vector

---

Define Documentation

#define VecIter (  vec, index   )     (vec->ppData + index)

Retrieve an iterator from an index into the vector. Parameters: vec   Pointer to the Vector to retrieve an iterator from. index   Index of the requested element. Returns: An iterator representing index.

#define VecOffset (  vec, iter   )     (iter - vec->ppData)

Get the offset of an iterator into a Vector. Parameters: vec   Pointer to the Vector that owns iter. iter   Pointer into vec to compare. Returns: An integer offset into the Vector's data array. Remarks: The return value is only valid if it is positive, and less than vec->lSize - otherwise iter was not created from vec.

---

Function Documentation

Vector* VectorCreate (  long   lSize, long   lDelta )

Create a new vector. Parameters: lSize   Number of elements to initially allocate. lDelta   Number of elements to reallocate by when more elements are added than can be accommodated. Returns: A pointer to the newly created Vector if successful, otherwise NULL. Remarks: Initially, lSize elements are allocated, and pushing values onto the back of the vector will be a fast operation (since the memory is already allocated). Once this array is exhausted, attempting to push another value will result in the array being increased by lDelta elements. However, pushing to the front of the vector will nearly always be slow since the whole array must be moved ahead.

void VectorDestroy (  Vector *   pVec )

Destroy a vector. Parameters: pVec   Vector to destroy. Remarks: This function will clean up and deallocate the vector specified by pVec. See also: ListDestroy for information about placing separately allocated pointers into the vector.

void** VectorFind (  Vector *   pVec, void **   ppIter, void *   pData, bool   bDirection )

Find a value in the vector. Parameters: pVec   Vector to search in. ppIter   Iterator in pVec to start from. pData   Data to search for. bDirection   Direction to search in: true is forwards, false is backwards. Returns: An iterator into the vector representing the first occurence of pData. See also: ListFind for remarks on finding values, and coping with multiple possible values.

void VectorPopBack (  Vector *   pVec )

Remove the last value from the vector. Parameters: pVec   Vector to remove from. Remarks: This is faster than VectorRemove for removing the last element from a vector. See also: VectorRemove , VectorPopFront

void VectorPopFront (  Vector *   pVec )

Remove the first value from the vector. Parameters: pVec   Vector to remove from. Remarks: This is faster than VectorRemove for removing the first element from a vector, but it is still considerably slower than removing the last element, since the internal data must all be moved. See also: VectorRemove , VectorPopBack

void** VectorPushBack (  Vector *   pVec, void *   pData )

Push an element on to the back of the vector. Parameters: pVec   Vector to append the data to. pData   Data to append. Returns: An iterator into the vector representing the newly added data if successful, otherwise NULL. Remarks: Adding a value to a vector will invalidate all iterators for that vector if a reallocation was necessary. However, the index of the value can be determined by using:   void **ppIter = VectorPushBack(pTheVector, pTheData); int iNewID = VecOffset(ppIter, pTheVector); If ppIter is NULL (i.e. allocation failed) then iNewID will be negative. See also: VecOffset

void** VectorPushFront (  Vector *   pVec, void *   pData )

Push an element on the the front of the vector. Parameters: pVec   Vector to prepend the data to. pData   Data to prepend. Returns: An iterator into the vector representing the newly added data if successful, otherwise NULL. See also: VectorPushBack for more information on invalidation of iterators, and how to retrieve the index of a newly added item.

void VectorRemove (  Vector *   pVec, void **   pIter )

Remove a value from the vector. Parameters: pVec   Vector to remove from. ppIter   Iterator to remove. Remarks: If ppIter is not valid, then nothing will happen, otherwise its connected element will be removed from the vector.

void** VectorSimpleFind (  Vector *   pVec, void *   pData )

Find a value in the vector. Parameters: pVec   Vector to search in. pData   Data to search for. Remarks: This function is a lot simpler and is used if you only need to find the first occurrence of an element in the vector. See also: VectorFind , ListFind

---

Variable Documentation

struct Vector Vector

Vector.

---