archeus/doc/pages/standard/vector.md

\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 <arc/std/vector.h>
#include <stdint.h>
#include <stdio.h>

//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 <arc/std/vector.h>
#include <stdint.h>
#include <stdio.h>

//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 <arc/std/vector.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>

//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);
}
```