diff --git a/doc/pages/standard/array.md b/doc/pages/standard/array.md index 92bea6c..9e95a0f 100644 --- a/doc/pages/standard/array.md +++ b/doc/pages/standard/array.md @@ -1,10 +1,16 @@ \page standard-array ARC_Array +# Basic Overview + The ARC_Array is a simple type, all it does is have a `void *` to store the array data in and a `uint32_t` to store the size in. This type is mostly a helper type to cut down on the number of parameters needed within Archeus' functions -Example: +The API Reference for ::ARC_Array can be found here: arc/std/array.h + +# Example + ```c #include +#include #include //initing the array (as it is a basic type there is no ARC_Array_Create or ARC_Array_Destroy) diff --git a/doc/pages/standard/bool.md b/doc/pages/standard/bool.md index 2a013bf..1db0df2 100644 --- a/doc/pages/standard/bool.md +++ b/doc/pages/standard/bool.md @@ -1,8 +1,13 @@ \page standard-bool ARC_Bool +# Basic Overview + The ::ARC_Bool type simple sets ::ARC_Bool to the `stdbool.h` `bool` type, ::ARC_True to true, and ::ARC_False to false. This type exists so that it can be overriden if a different boolean type should be used (like with opengl) -Basic Example: +The API Reference for ::ARC_Bool can be found here: arc/std/bool.h + +# Basic Example + ```c #include @@ -14,7 +19,8 @@ if(example == ARC_True){ } ``` -Override Example: +# Override Example + ```c #include diff --git a/doc/pages/standard/chemical.md b/doc/pages/standard/chemical.md index 81b2316..e698e8b 100644 --- a/doc/pages/standard/chemical.md +++ b/doc/pages/standard/chemical.md @@ -1,3 +1,5 @@ \page standard-chemical ARC_Chemical This type is being actively worked on. It will be a config type to read in .chemical files. The name was chosen from the four ethers that Archeus can be broken down into (Chemical, Life, Light, and Reflective) + +*This page will be written after completing the ::ARC_Chemical type* diff --git a/doc/pages/standard/errno.md b/doc/pages/standard/errno.md index 33a25b7..5346c61 100644 --- a/doc/pages/standard/errno.md +++ b/doc/pages/standard/errno.md @@ -2,15 +2,16 @@ *Note: this file is being actively worked on and might change during minor updates* -## About +# Basic Overview arc/std/errno.h is used for handling errors as well as printing to debug. It defines a global `uint32_t` ::arc_errno, as well as a global `FILE` ::arc_errno_log_file. For now it just has printing errors, but in the future it is planned to have warnings and general logs added. For error logs to be printed, `ARC_DEBUG` needs to be defined when compiled. -## Basic Error Handling +# Basic Error Handling When throwing errors, ::arc_errno should usually be set to an ARC_ERRNO_ define describing the error. After setting ::arc_errno it is strongly recommended to log that the error happened (this really helps when debugging). -Basic Example: +# Basic Example + ```c #include @@ -27,11 +28,12 @@ void ARC_Example_ThrowNullError(){ } ``` -## Error Handling With More Information +# Error Handling With More Information Sometimes the error will have data that could be helpful when debugging, so there is also a log macro that can log the error with variables added. The formatting is the same as printf. -Example With Variables: +# Example With Variables + ```c #include #include @@ -50,11 +52,12 @@ void ARC_Example_ThrowPathError(ARC_String *path){ } ``` -## Overriding Output File +# Overriding Output File By default the logs will output to stdout, however this can has an override by defining ARC_DEBUG_LOG_STREAM_OVERRIDE -Example of Overriding Log Stream: +# Example of Overriding Log Stream: + ```c //when compiling, ARC_DEBUG_LOG_STREAM_OVERRIDE needs to be set, then just add diff --git a/doc/pages/standard/queue.md b/doc/pages/standard/queue.md index 9ccfdd1..c5591a4 100644 --- a/doc/pages/standard/queue.md +++ b/doc/pages/standard/queue.md @@ -1 +1,3 @@ \page standard-queue ARC_Queue + +*This page will be written after refactoring the ::ARC_Queue type* diff --git a/doc/pages/standard/stack.md b/doc/pages/standard/stack.md index 2788b5d..5d03ce9 100644 --- a/doc/pages/standard/stack.md +++ b/doc/pages/standard/stack.md @@ -1 +1,3 @@ \page standard-stack ARC_Stack + +*This page will be written after refactoring the ::ARC_Stack type* diff --git a/doc/pages/standard/string.md b/doc/pages/standard/string.md index 25fd25c..0eafa3c 100644 --- a/doc/pages/standard/string.md +++ b/doc/pages/standard/string.md @@ -1 +1,3 @@ \page standard-string ARC_String + +*This page will be written after refactoring the ::ARC_String type* diff --git a/doc/pages/standard/time.md b/doc/pages/standard/time.md index a4af705..4efbcac 100644 --- a/doc/pages/standard/time.md +++ b/doc/pages/standard/time.md @@ -1 +1,3 @@ \page standard-time ARC_Time + +*This page will be written after refactoring the ::ARC_Time type* diff --git a/doc/pages/standard/vector.md b/doc/pages/standard/vector.md index 73b0d52..0e1a4f3 100644 --- a/doc/pages/standard/vector.md +++ b/doc/pages/standard/vector.md @@ -1 +1,171 @@ \page standard-vector ARC_Vector + +# Basic Overview + +The ::ARC_Vector type is a simple "expandable" array. The array itself does not actually expand, but it double or halves in size and copies the contents into the new array. + +The API Reference for ::ARC_Vector can be found here: arc/std/vector.h + +# Basic Example: + +```c +#include +#include +#include + +//creating an array with no callbacks (the simplest example of the array) +ARC_Vector *vector; +ARC_Vector_Create(&vector, NULL, NULL); + +//for the example we are using a stack pointer +//this is not recommended unless it is freed within the scope it is called +uint32_t value0 = 10; +uint32_t value1 = 11; +uint32_t value2 = 12; + +//add the values to the vector +ARC_Vector_Add(vector, &value0); +ARC_Vector_Add(vector, &value1); +ARC_Vector_Add(vector, &value2); + +//create the variable that will be used to get an index +uint32_t *valueRef = NULL; + +//print the values within the vector +for(uint32_t index = 0; index < ARC_Vector_GetSize(vector); index++){ + //cast the return value back to what it initially was + valueRef = (int32_t *)ARC_Vector_Get(vector, index); + + //print out the index and value + printf("%d) %d\n", index, *value); +} + +//cleanup +ARC_Vector_Destroy(vector); +``` + +# Comparison Callback + +A handy feature of this implmentation fo a vector is the ability to add a comparison callback. This callback can be used to remove an item that matches based on a provided function. + +# Comparison Callback Example + +```c +#include +#include +#include + +//the comparison callback to check if two integer pointers hold the same value +ARC_Bool ARC_Example_VectorCompareDataFn(void *dataA, void *dataB){ + return (ARC_Bool)(*(int32_t *)dataA == *(int32_t *)dataB); +} + +int main(){ + //creating an array with a comparison function, but not a destroy function + ARC_Vector *vector; + ARC_Vector_CompareDataFn exampleCompareDataFn = ARC_Example_VectorCompareDataFn; + ARC_Vector_Create(&vector, &exampleCompareDataFn, NULL); + + //for the example we are using a stack pointer + //this is not recommended unless it is freed within the scope it is called + int32_t value0 = 10; + int32_t value1 = 11; + int32_t value2 = 12; + int32_t value3 = 13; + + //add the values to the vector + ARC_Vector_Add(vector, &value0); + ARC_Vector_Add(vector, &value1); + ARC_Vector_Add(vector, &value2); + ARC_Vector_Add(vector, &value3); + + //create the variable of the number we want to remove + int32_t removeValue = 12; + + //print the values within the vector + for(uint32_t index = 0; index < ARC_Vector_GetSize(vector); index++){ + //cast the return value back to what it initially was + valueRef = (int32_t *)ARC_Vector_Get(vector, index); + + //print out the index and value + printf("%d) %d\n", index, *value); + } + + //remove the value + ARC_Vector_Remove(vector, &removeValue); + + //print the values again to show that the value was removed + for(uint32_t index = 0; index < ARC_Vector_GetSize(vector); index++){ + //cast the return value back to what it initially was + valueRef = (int32_t *)ARC_Vector_Get(vector, index); + + //print out the index and value + printf("%d) %d\n", index, *value); + } + + //cleanup + ARC_Vector_Destroy(vector); +} +``` + +# Destruction Callback + +As the vector takes a pointer, usually that pointer is allocated right before being added. To simplify the cleanup of the vector's values there is a destruction callback. This callback is run on clear, remove, and destroy to free all the memory within the vector. + +# Destruction Callback Example + +```c +#include +#include +#include +#include + +//the destruction callback to free the allocated int32_t values +void ARC_Example_VectorDestroyDataFn(void *data){ + free((int32_t *)data); +} + +//helper function that adds a int32_t to a vector, written to cut back on duplicate code +void ARC_Example_AddNewInt32ToVector(ARC_Vector *vector, uint32_t value){ + //this malloc will be freed by the vector destroy data function callback + int32_t *newValue = (int32_t)malloc(sizeof(int32_t)); + *newValue = value; + ARC_Vector_Add(vector, newValue); +} + +int main(){ + //creating an array with a comparison function, but not a destroy function + ARC_Vector *vector; + ARC_Vector_DestroyDataFn exampleDestroyDataFn = ARC_Example_VectorDestroyDataFn; + ARC_Vector_Create(&vector, NULL, exampleDestroyDataFn); + + ARC_Example_AddNewInt32ToVector(vector, 12); + ARC_Example_AddNewInt32ToVector(vector, 13); + ARC_Example_AddNewInt32ToVector(vector, 14); + ARC_Example_AddNewInt32ToVector(vector, 15); + + //print the values within the vector + for(uint32_t index = 0; index < ARC_Vector_GetSize(vector); index++){ + //cast the return value back to what it initially was + valueRef = (int32_t *)ARC_Vector_Get(vector, index); + + //print out the index and value + printf("%d) %d\n", index, *value); + } + + //example to demonstrate that there is no memory leak on removal due to the destroy callback + ARC_Vector_RemoveIndex(vector, 0); + + //print the values again to show that the value was removed + for(uint32_t index = 0; index < ARC_Vector_GetSize(vector); index++){ + //cast the return value back to what it initially was + valueRef = (int32_t *)ARC_Vector_Get(vector, index); + + //print out the index and value + printf("%d) %d\n", index, *value); + } + + //cleanup + ARC_Vector_Destroy(vector); +} +```