API List Page 1

Contents

Initialization Macros

All Initialization Macros can be located in "geneticc/list/geneticc_list.h

• new_List
• List_Init
• Array_To_List
• Array_CopyTo_List
• Array_Init_List
• Array_CopyInit_List
• List_ToArray
• List_Delete

Get/Set Macros

All Get/Set Macros can be located in "geneticc/list/geneticc_list.h

• List_Array
• List_Get
• List_Get_Std
• List_Set
• List_Val

Size and Capacity Macros

All macros can be located in "geneticc/list/geneticc_list.h

• List_Capacity
• List_Get_CapacitySize
• List_Set_Capacity
• List_Get_Capacity
• List_Size
• List_Count
• List_Realign
• List_TrimExcess
• List_AdjustHead
• List_AdjustTail

---

Initialization Macros

new_List

Allocates and Initializes a list.

Prototypes/Overloads

• new_List(elem_size)
• new_List(elem_size, capacity)

Parameters

Name	Type	Optional	Description
elem_size	element_size_t	No	How many bytes one element equals.
capacity	capacity_count_t	Yes	The initial size of the internal array. (Default = 4)

Returns

LIST_PTR (list_t*)

A pointer to the newly allocated list.

Example

LIST_PTR list = new_List(1); //Allocates and initializes a list which holds 1 byte values of any type, with a capacity of 4.

---

List_Init

Properly initializes a list_t.

Prototypes/Overloads

• List_New(out_list, elem_size)
• List_New(out_list, elem_size, capacity)

Parameters

Name	Type	Optional	Description
*out_list	LIST_PTR	No	Pointer to the list_t you are initializing..
elem_size	element_size_t	No	How many bytes one element equals.
capacity	capacity_count_t	Yes	The initial size of the internal array. (Default = 4)

Returns

void

Example

list_t list;
List_Init(&list, 1);    //Initializes a list which holds 1 byte values of any type, with a capacity of 4.

---

Array_To_List

Initializes a list from an already existing array.

Prototypes/Overloads

• Array_To_List(array)
• Array_To_List(array, length)
• Array_To_List(array, length, populated_length)
• Array_To_List(array, length, populated_length, elem_size)

Parameters

Name	Type	Optional	Description
array	ARRAY_PTR	No	Pointer to the start of the array.
length	length_t	Yes	The length of the array.
populated_length	length_t	Yes	The amount of elements currently in the array.
elem_size	element_size_t	Yes	The size of a single element in the array. *Required if passing a pointer whos type does not represent the internal values. (ARRAY_PTR, void*)

Returns

LIST_PTR(list_t*)

A pointer to the newly allocated list.

Example

char array[10];

for(int i = 0; i < 5; i++)
{
	//Populate 5 elements in the array.
	array[i] = i;
}

//Create a list from the array, with a capacity of 10, and a Count of 5.
//Internal array points to "array."
LIST_PTR list = Array_To_List(&array, 10, 5); 

capacity_count_t capacity = List_Get_Capacity(list); //Returns 10
length_t count = List_Count(list);                   //Returns 5

---

Array_CopyTo_List

Allocates and Initializes a list from an already existing array. Copies the array into a new block of memory. (Use Array_To_list to use the same array)

Prototypes/Overloads

• Array_CopyTo_List(array)
• Array_CopyTo_List(array, length)
• Array_CopyTo_List(array, length, populated_length)
• Array_CopyTo_List(array, length, populated_length, elem_size)

Parameters

Name	Type	Optional	Description
array	ARRAY_PTR	No	Pointer to the start of the array.
length	length_t	Yes	The length of the array.
populated_length	length_t	Yes	The amount of elements currently in the array.
elem_size	element_size_t	Yes	The size of a single element in the array. *Required if passing a pointer whos type does not represent the internal values. (ARRAY_PTR, void*)

Returns

LIST_PTR(list_t*)

A pointer to the newly allocated list.

Example

char array[10];

for(int i = 0; i < 5; i++)
{
	//Populate 5 elements in the array.
	array[i] = i;
}

//Create a list from the array, with a capacity of 10, and a Count of 5.
LIST_PTR list = Array_To_List(&array, 10, 5); 

capacity_count_t capacity = List_Get_Capacity(list); //Returns 10
length_t count = List_Count(list);                   //Returns 5

//list->array != &array

---

Array_Init_List

Initializes a list from an already existing array.

Prototypes/Overloads

• Array_Init_List(array, out_list)
• Array_Init_List(array, length, out_list)
• Array_Init_List(array, length, populated_length, out_list)
• Array_Init_List(array, length, populated_length, elem_size, out_list)

Parameters

Name	Type	Optional	Description
array	ARRAY_PTR	No	Pointer to the start of the array.
length	length_t	Yes	The length of the array.
populated_length	length_t	Yes	The amount of elements currently in the array.
elem_size	element_size_t	Yes	The size of a single element in the array. *Required if passing a pointer whos type does not represent the internal values. (ARRAY_PTR, void*)
*out_list	LIST_PTR	No	Pointer to the list_t you are initializing..

Returns

void

Example

char array[10];
list_t list;

for(int i = 0; i < 5; i++)
{
	//Populate 5 elements in the array.
	array[i] = i;
}

//Create a list from the array, with a capacity and count of 10.
//Array_Init_List(&array, &list); 

//The array only has 5 valid values, so we must pass the length and populated_length.

//Create a list from the array, with a capacity of 10,
//and a Count of 5.
Array_Init_List(&array, 10, 5, &list); 

capacity_count_t capacityCount = List_Get_Capacity(list);     //Returns 10
capacity_size_t capacitySize = List_Get_CapacitySize(list);   //Returns 10
length_t count = List_Count(list);                            //Returns 5
size_t size= List_Size(list);                                 //Returns 5

//list->array == &array

---

Array_CopyInit_List

Allocates and initializes a list, and then copies an already existing array to the list.

Prototypes/Overloads

• Array_CopyInit_List(array, out_list)
• Array_CopyInit_List(array, length, out_list)
• Array_CopyInit_List(array, length, populated_length, out_list)
• Array_CopyInit_List(array, length, populated_length, elem_size, out_list)

Parameters

Name	Type	Optional	Description
array	ARRAY_PTR	No	Pointer to the start of the array.
length	length_t	Yes	The length of the array.
populated_length	length_t	Yes	The amount of elements currently in the array.
elem_size	element_size_t	Yes	The size of a single element in the array. *Required if passing a pointer whos type does not represent the internal values. (ARRAY_PTR, void*)
*out_list	LIST_PTR	No	Pointer to the list_t you are initializing..

Returns

void

Example

int array[10];
list_t list;

for(int i = 0; i < 5; i++)
{
	//Populate 5 elements in the array.
	array[i] = i;
}

//Create a list from the array, with a capacity of 10,
//and a Count of 5.
Array_CopyInit_List(&array, 10, 5, &list); 

capacity_count_t capacityCount = List_Get_Capacity(list);     //Returns 10
capacity_size_t capacitySize = List_Get_CapacitySize(list);   //Returns 40
length_t count = List_Count(list);                            //Returns 5
size_t size= List_Size(list);                                 //Returns 20

//list->array != &array

---

List_ToArray

Allocates a new array and copies the elements from the list.

Prototypes/Overloads

• List_ToArray(list)

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list.

Returns

ARRAY_PTR

Example

char array[5] = {1, 2, 3, 4, 5};

LIST_PTR list = Array_CopyTo_List(&array);

List_Remove(list, 1); //Result = {..., 2, 3, 4, 5}

//Allocates an array that can fit all the list's elements, discarding the unpopulated elements.
char array = List_ToArray(list); //Result = {2, 3, 4, 5}

---

List_Delete

Frees the list and its internal array from memory.

Prototypes/Overloads

• List_Delete(list)

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list.

Returns

void

Example

char array[5] = {1, 2, 3, 4, 5};

LIST_PTR list = Array_CopyTo_List(&array);

/*
Do stuff with the list.
*/

//Free the internal array, and the list.
List_Delete(list);

---

Get/Set Macros

List_Array

Gets a pointer aligned to the first element in the array.

Prototypes/Overloads

• List_Array(list)

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list.

Returns

ARRAY_PTR

Returns a pointer to the first element in the internal array.

Is equal to list->array + list->tail;

Example

char array[5] = {1, 2, 3, 4, 5};

LIST_PTR list = Array_To_List(&array);

//Remove the first 2 elements from the list.
List_RemoveRange(list, 0, 2); //list->array = {0, 0, 3, 4, 5} | First element = [2]

//list->array[0] = 1;           does not set the first item.
//list->array[list->tail] = 1   does set the first item, but is an annoyance.

List_Array(list)[0] = 1;        //So instead we can use List_Array(list) | list->array = {0, 0, 1, 4, 5}

Remarks

List_Array allows you to set a specific index in the array using [].

When tail is greater than 0, the first element in the array is not [0], and doing list->array[0] = 1; will not set the first item. To set the first item you would have to do list->array[list->tail]; List_Array does that for you, so setting the first item would look like List_Array(list)[0] = 1;

---

List_Get

Moves the tail, changing the size of the internal array.

Prototypes/Overloads

• List_Get(list)

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list.

Returns

ELEMENT_PTR

Pointer to the element at the index, or null if the index was out of range.

Example

char array[5] = {1, 2, 3, 4, 5};

LIST_PTR list = Array_To_List(&array);

List_AdjustTail(list, 2, true);    //List->array = {0, 0, 3, 4, 5}

char* element = List_Get(list, 0); //Returns pointer to index 0, which is the 3.

---

List_Get_Std

Standard value types only

Gets a value which resides at the specified index in the list.

Prototypes/Overloads

• List_Get_Std(list, index, type)

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list. `Can only be holding a standard data type.`
index	index_t	No	Index of the value
type	Any Standard Value	No	Any value which is equal to the list'sdata type. This is used to do a generic cast in a macro.

Returns

Any Standard Data Type

The value residing at the index.

Example

char array[5] = {1, 2, 3, 4, 5};

LIST_PTR list = Array_To_List(&array);

List_AdjustTail(list, 2, true);    //List->array = {0, 0, 3, 4, 5}

char value = List_Get_Std(list, 0, value); //Returns 3. *Value is passed as the third argument to get the type to cast to.

---

List_Set

Sets the element at the index to the value.

Prototypes/Overloads

• List_Set(list, value, index)

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list. `Can only be holding a standard data type.`
value	A value or pointer to a value.	No	The value to set.
index	index_t	No	Index of the element to set.

Returns

bool

True if the value was set, or null if the index was out of range.

Example

char array[5] = {1, 2, 3, 4, 5};

LIST_PTR list = Array_To_List(&array);

List_Set(list, 0, 2); //Result = {1, 2, 0, 4, 5}

---

List_Val

Note: The 2 overloads do completely different things. One will set a value, and the other gets a value.

Either gets a value from the index, or sets the value at the index.

Prototypes/Overloads

• ELEMENT_PTR List_Val(list, index) 'Gets a pointer to the value at the index'
• bool List_Val(list, value, index) Sets the value at the index

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list.
index	index_t	No/td>	The index of the value to get or set.
value	Any Value or Pointer	Yes/td>	The value to set. `Passing this parameter will set the value, omitting will get a pointer to the value.`

Returns

ELEMENT_PTR

Pointer to the value at the specified index..

or

bool

True if the capacity was able to bet set.

False if the index was out of range.

Example

char array = {1, 2, 3, 4, 5};
LIST_PTR list = Array_To_List(&array);

char* get = List_Val(list, 2);           //Result = pointer to index[2]
char getV = *(char*)List_Val(list, 2);   //Result = 3

List_Val(list, 0, 2);

char getV = *(char*)List_Val(list, 2);   //Result = 0

---

Size and Capacity Macros

List_Capacity

Note: The 2 overloads do completely different things. One will set the capacity, and the other gets the capacity.

Either returns the current capacity, or sets a new capacity for the list.

Prototypes/Overloads

• capacity_count_t List_Capacity(list) Gets the capacity
• bool List_Capacity(list, capacity) Sets the capacity

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list.
*capacity	capacity_count_t	Yes/td>	The new capacity. `Passing this parameter will set the list's capacity, omitting will get the capacity.`

Returns

capacity_count_t

The current capacity of the list (how many elements fit in the internal array).

or

bool

True if the capacity was able to bet set.

False if the capacity is greater than the maximum, or less than the count (How many elements in the array are populated).

Example

LIST_PTR list = new_List(sizeof(int));

capacity_count_t capacityCount = List_Capacity(list);           //Returns 4
capacity_size_t capacitySize =   List_Get_CapacitySize(list);   //Returns 16
length_t count = List_Count(list);                              //Returns 0

List_Capacity(list, 10);

capacity_count_t capacityCount = List_Capacity(list);           //Returns 10
capacity_size_t capacitySize =   List_Get_CapacitySize(list);   //Returns 40
length_t count = List_Count(list);                              //Returns 0

---

List_Get_CapacitySize

Same as list->capacity

Gets the capacity represented as bytes.

Prototypes/Overloads

• List_Get_CapacitySize(list)

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list.

Returns

capacity_size_t

The current capacity of the list, represented as bytes.

Example

LIST_PTR list = new_List(sizeof(int));

capacity_size_t capacitySize =   List_Get_CapacitySize(list);   //Returns 16
same as
capacity_size_t capacitySize = list->capacity;                  //Returns 16

---

List_Get_Capacity

Gets the capacity of of the list, represented as element count.

Prototypes/Overloads

• List_Get_Capacity(list)

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list.
*capacity	capacity_count_t	No/td>	The new capacity.

Returns

bool

True if the capacity was able to bet set.

False if the capacity is greater than the maximum, or less than the count (How many elements in the array are populated).

Example

LIST_PTR list = new_List(sizeof(int));

capacity_count_t capacityCount = List_Get_Capacity(list);           //Returns 4

---

List_Size

Gets the total size of elements in the list.

Prototypes/Overloads

• List_Size(list)

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list.

Returns

size_t

Size of the populated elements in the list represented as bytes. Not equal to the size of the internal array.

Example

LIST_PTR list = new_List(sizeof(int));

size_t size = List_Size(list);           //Returns 0

List_Add(list, 1);

size = List_Size(list);                   //Returns 4

---

List_Count

Gets the total count of elements in the list.

Prototypes/Overloads

• List_Count(list)

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list.

Returns

length_t

Count of the populated elements in the list. Not equal to the size of the internal array.

Example

LIST_PTR list = new_List(sizeof(int));

length_t size = List_Count(list);           //Returns 0

List_Add(list, 1);

size = List_Count(list);                    //Returns 1

---

List_Realign

Moves the elements in the array so the tail is at index 0.

Prototypes/Overloads

• List_Realign(list)

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list.

Returns

void

Example

char array = {1, 2, 3, 4, 5};
LIST_PTR list = Array_To_List(&array);

int tail = list->tail;        //Equals 0

//Remove the first 2 elements from the list.
List_RemoveRange(list, 0, 2); //List->array = {0, 0, 3, 4, 5};

tail = list->tail;            //Equals 2

List_Realign(list);           //List->array = {3, 4, 5, 0, 0};

tail = list->tail;            //Equals 0

---

List_TrimExcess

Realigns the internal array, sets the capacity to the size of the array, and then reallocates the array.

Prototypes/Overloads

• List_TrimExcess(list)

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list.

Returns

void

Example

char array[10];

for(int i = 0; i < 5; i++)
{
	//Populate 5 elements in the array.
	array[i] = i;
}

LIST_PTR list = Array_To_List(&array, 10, 5); //List->array = {0, 1, 2, 3, 4, 0, 0, 0, 0, 0};

int tail = list->tail;        //Equals 0
int head = list->head;        //Equals 5


//Remove the first 2 elements from the list.
List_RemoveRange(list, 0, 2); //List->array = {0, 0, 2, 3, 4, 0, 0, 0, 0, 0};

tail = list->tail;            //Equals 2

List_Realign(list);           //List->array = {2, 3, 4};

tail = list->tail;            //Equals 0
head = list->head;            //Equals 3

---

List_AdjustHead

Moves the head, changing the size of the internal array, while making sure the head does not reach an invalid state.

Prototypes/Overloads

• List_AdjustHead(list, n)
• List_AdjustHead(list, n, erase)

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list.
n	int	No	How many elements the head will be moved.
erase	bool	No	If head is less than its initial value. Should the memory be set to 0?

Returns

length_t

Returns the new size of the list.

Example

char array[5] = {1, 2, 3, 4, 5};

LIST_PTR list = Array_To_List(&array);

int head = list->head;           //Equals 5

List_AdjustHead(list, -2, true); //List->array = {1, 2, 3, 0, 0}

int head = list->head;           //Equals 3 

List_AdjustHead(list, 4);        //ERROR, out of range

Remarks

Positive value will add values, negative will remove values.

Nothing will change if the result will be less than the tail, or greater than the capacity. An error state will be reached if the head is less than tail, or greater than the capacity

---

List_AdjustTail

Moves the tail, changing the size of the internal array.

Prototypes/Overloads

• List_AdjustTail(list, n)
• List_AdjustTail(list, n, erase)

Parameters

Name	Type	Optional	Description
list	LIST_PTR	No	Pointer to the list.
n	int	No	How many elements the head will be moved.
erase	bool	No	If head is less than its initial value. Should the memory be set to 0?

Returns

length_t

Returns the new size of the list.

Example

char array[5] = {1, 2, 3, 4, 5};

LIST_PTR list = Array_To_List(&array);

int tail = list->tail;           //Equals 0

List_AdjustTail(list, 2, true);  //List->array = {0, 0, 3, 4, 5}

tail = list->tail;               //Equals 2 

List_AdjustTail(list, 2);        //List->array = {0, 0, 3, 4, 5}

tail = list->tail;               //Equals 4
int size = List_Size(list);      //Equals 1

List_AdjustTail(list, -5);       //ERROR, out of range

Remarks

Positive value will remove values, negative will add values.

Nothing will happen if the tail will be less than zero, or greater than the head.

An error state will be reached if the tail is less than zero, or greater than the head

---