archeus/include/arc/std/vector/inline.h

#ifndef ARC_STD_VECTOR_INLINE_H_
#define ARC_STD_VECTOR_INLINE_H_

#ifdef __cplusplus
extern "C" {
#endif

#include "arc/std/array.h"
#include "arc/std/vector.h"
#include <stdint.h>

/**
 * @brief a dynamic array type that stores elements next to eachother
*/
typedef struct ARC_VectorInline ARC_VectorInline;

/**
 * @brief creates an ARC_VectorInline which is an "expandable" array, this version allocates an array with set length for segments instead of void pointers for the data
 *
 * @note this vector relies on correct casting to not have errors, and is a lot less safe than "arc/std/vector.h",
 *       it is recommended that you use "arc/std/vector.h" if you don't have a specific reason to use this type
 * @note to avoid writing a ton of callback types, this will use callback types defined in "arc/std/vector.h"
 * @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] vectorInline  ARC_VectorInline to initialize
 * @param[in]  typeSize      the size of the type to store within the inline vector
 * @param[in]  compareDataFn a callback that checks if data stored in the array matches,
 *                           if set to NULL and ARC_VectorIndex_Remove is called, an error will be thrown
 * @param[in]  destroyDataFn a callback that frees an item on remove or clear, can be set to NULL to do nothing
*/
void ARC_VectorInline_Create(ARC_VectorInline **vectorInline, uint32_t typeSize, ARC_Vector_CompareDataFn *compareDataFn, ARC_Vector_DestroyDataFn *destroyDataFn);

/**
 * @brief destroys an ARC_VectorInline
 *
 * @note this will only free the items if destroyDataFn is passed in on creation
 *
 * @param[in] vector ARC_VectorInline to free
*/
void ARC_VectorInline_Destroy(ARC_VectorInline *vectorInline);

/**
 * @brief adds an item to an ARC_VectorInline
 *
 * @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_VectorInline to add to
 * @param[in] data   data that is being added
*/
void ARC_VectorInline_Add(ARC_VectorInline *vectorInline, void *data);

/**
 * @brief removes an item from a matching item in an ARC_VectorInline
 *
 * @note this function uses the ARC_Vector_CompareDataFn that the ARC_VectorInline was created with
 * @note this function will not throw an error if there is no match
 * @note this function will call ARC_VectorInline_RemoveIndex, so it's notes are also applicable to this function
 *
 * @param[in] vectorInline ARC_VectorInline to remove from
 * @param[in] data         matching data to remove
*/
void ARC_VectorInline_Remove(ARC_VectorInline *vectorInline, void *data);

/**
 * @brief removes an item from an ARC_VectorInline at an index
 *
 * @note this function will error if trying to remove an index that is outside the bounds of the ARC_VectorInline
 * @note this function will use ARC_Vector_DeleteDataFn if it was set in the ARC_VectorInline_Create function
 *
 * @param[in] vectorInline ARC_VectorInline to remove from
 * @param[in] index        position of data to remove
*/
void ARC_VectorInline_RemoveIndex(ARC_VectorInline *vectorInline, uint32_t index);

/**
 * @brief clears all items from a vector
 *
 * @note this function will call ARC_VectorInline_RemoveIndex, so it's notes are also applicable to this function
 *
 * @param[in] vector ARC_VectorInline to clear
*/
void ARC_VectorInline_Clear(ARC_VectorInline *vectorInline);

/**
 * @brief gets the current size of an ARC_VectorInline as an unsigned 32 bit integer
 *
 * @param[in] vector ARC_VectorInline to get current size from
 *
 * @return the current size as a unsigned 32 bit integer
*/
uint32_t ARC_VectorInline_GetSize(ARC_VectorInline *vectorInline);

/**
 * @brief gets an item from an ARC_VectorInline at a position index
 *
 * @note this function will error if trying to get an index that is outside the bounds of the ARC_VectorInline
 *
 * @param[in] vectorInline ARC_VectorInline to get data from
 * @param[in] index        position of data to get
 *
 * @return a void * item, or NULL on error
*/
void *ARC_VectorInline_Get(ARC_VectorInline *vectorInline, uint32_t index);

/**
 * @brief gets the data from the vector as an ARC_Array
 *
 * @note this function will does not copy the data it returns, so changes will affect the contents of the vector inline
 *
 * @param[in] vectorInline ARC_VectorInline to get data from
 *
 * @return an ARC_Array that holds the current contents of the vector inline
*/
ARC_Array ARC_VectorInline_GetData(ARC_VectorInline *vectorInline);

#ifdef __cplusplus
}
#endif

#endif // !ARC_STD_VECTOR_INLINE_H_