Loading...
Searching...
No Matches
vector.h
Go to the documentation of this file.
/**
* @file vector.h
*
* @brief creates and outlines a dynamic array type and its functions
*/
#ifndef ARC_STD_VECTOR_H_
#define ARC_STD_VECTOR_H_
#ifdef __cplusplus
extern "C" {
#endif
#include "arc/std/bool.h"
#include <stdint.h>
/**
* @addtogroup ARC_Vector
* Additional documentation for group 'ARC_Vector'
* @{
*/
/**
* @brief a dynamic array type
*/
typedef struct ARC_Vector ARC_Vector;
/**
* @brief a callback that allows the user to define a way to check the data stored in a vector for a match
*
* @param[in] dataA the first data to check
* @param[in] dataB the second data to check
*
* @return ARC_True when dataA == dataB, and ARC_False otherwise
*/
typedef ARC_Bool (* ARC_Vector_CompareDataFn)(void *dataA, void *dataB);
/**
* @brief a callback that cleans up memory when it is removed from the vector
*
* @param[in] data the item to destroy
*/
typedef void (* ARC_Vector_DestroyDataFn)(void *data);
/**
* @brief creates an ARC_Vector which is an "expandable" array
*
* @note for this basic implementation, the array will double in size every time the capacity is hit
* @note the array will also half in size when the array is only half filled
*
* @param[out] vector ARC_Vector to initialize
* @param[in] compareDataFn a callback that checks if data stored in the array matches,
* if set to NULL and ARC_Vector_Remove is called, the pointer addresses will be compared
* @param[in] destroyDataFn a callback that frees an item on remove or clear, can be set to NULL to do nothing
*/
void ARC_Vector_Create(ARC_Vector **vector, ARC_Vector_CompareDataFn *compareDataFn, ARC_Vector_DestroyDataFn *destroyDataFn);
/**
* @brief destroys an ARC_Vector
*
* @note this will not free the items stored in the vector
* @note please make sure to clear and free the children before destroying an ARC_Vector
*
* @param[in] vector ARC_Vector to free
*/
void ARC_Vector_Destroy(ARC_Vector *vector);
/**
* @brief adds an item to an ARC_Vector
*
* @note this will error if you add more than 4,294,967,295 items (the max value of an unsigned int 32)
*
* @param[in] vector ARC_Vector to add to
* @param[in] data data that is being added
*/
void ARC_Vector_Add(ARC_Vector *vector, void *data);
/**
* @brief removes an item from a matching item in an ARC_Vector
*
* @note this function uses the ARC_Vector_CompareDataFn that the ARC_Vector was created with
* @note this function will not throw an error if there is no match
* @note this function will call ARC_Vector_RemoveIndex, so it's notes are also applicable to this function
*
* @param[in] vector ARC_Vector to remove from
* @param[in] data matching data to remove
*/
void ARC_Vector_Remove(ARC_Vector *vector, void *data);
/**
* @brief removes an item from an ARC_Vector at an index
*
* @note this function will error if trying to remove an index that is outside the bounds of the ARC_Vector
* @note this function will use ARC_Vector_DeleteDataFn if it was set in the ARC_Vector_Create function
*
* @param[in] vector ARC_Vector to remove from
* @param[in] index position of data to remove
*/
void ARC_Vector_RemoveIndex(ARC_Vector *vector, uint32_t index);
/**
* @brief clears all items from a vector
*
* @note this function will call ARC_Vector_RemoveIndex, so it's notes are also applicable to this function
*
* @param[in] vector ARC_Vector to clear
*/
void ARC_Vector_Clear(ARC_Vector *vector);
/**
* @brief gets the current size of an ARC_Vector as an unsigned 32 bit integer
*
* @param[in] vector ARC_Vector to get current size from
*
* @return the current size as a unsigned 32 bit integer
*/
uint32_t ARC_Vector_GetSize(ARC_Vector *vector);
/**
* @brief gets an item from an ARC_Vector at a position index
*
* @note this function will error if trying to get an index that is outside the bounds of the ARC_Vector
*
* @param[in] vector ARC_Vector to get data from
* @param[in] index position of data to get
*
* @return a void * item, or NULL on error
*/
void *ARC_Vector_Get(ARC_Vector *vector, uint32_t index);
/*! @} */
#ifdef __cplusplus
}
#endif
#endif // !ARC_STD_VECTOR_H_
bool.h
ARC_Bool
#define ARC_Bool
Definition bool.h:10
ARC_Vector_DestroyDataFn
void(* ARC_Vector_DestroyDataFn)(void *data)
a callback that cleans up memory when it is removed from the vector
Definition vector.h:43
ARC_Vector_GetSize
uint32_t ARC_Vector_GetSize(ARC_Vector *vector)
gets the current size of an ARC_Vector as an unsigned 32 bit integer
ARC_Vector_Get
void * ARC_Vector_Get(ARC_Vector *vector, uint32_t index)
gets an item from an ARC_Vector at a position index
ARC_Vector
struct ARC_Vector ARC_Vector
a dynamic array type
Definition vector.h:26
ARC_Vector_Add
void ARC_Vector_Add(ARC_Vector *vector, void *data)
adds an item to an ARC_Vector
ARC_Vector_CompareDataFn
ARC_Bool(* ARC_Vector_CompareDataFn)(void *dataA, void *dataB)
a callback that allows the user to define a way to check the data stored in a vector for a match
Definition vector.h:36
ARC_Vector_Remove
void ARC_Vector_Remove(ARC_Vector *vector, void *data)
removes an item from a matching item in an ARC_Vector
ARC_Vector_Destroy
void ARC_Vector_Destroy(ARC_Vector *vector)
destroys an ARC_Vector
ARC_Vector_RemoveIndex
void ARC_Vector_RemoveIndex(ARC_Vector *vector, uint32_t index)
removes an item from an ARC_Vector at an index
ARC_Vector_Clear
void ARC_Vector_Clear(ARC_Vector *vector)
clears all items from a vector
ARC_Vector_Create
void ARC_Vector_Create(ARC_Vector **vector, ARC_Vector_CompareDataFn *compareDataFn, ARC_Vector_DestroyDataFn *destroyDataFn)
creates an ARC_Vector which is an "expandable" array