-
Notifications
You must be signed in to change notification settings - Fork 0
TRL_Chain
A TRL_Chain is basically a Linked List.
TRL_Chain handles creation, deletion and other cumbersome tasks itself.
But to destroy a TRL_Chain, you need to call the TRL_Chain_Destroy function youself.
There are two main structures for a TRL_Chain. one is TRL_Chain that acts as the controller and the other is TRL_ChainItem that acts as a Node in a Linked List.
{
void *Data;
struct TRL_ChainItem *Previous;
struct TRL_ChainItem *Next;
}-
Datais the actual data that the ChainItem aka Node stores. -
Previousstores the pointer to the previous ChainItem in the Chain -
Nextstores the pointer to the next ChainItem in the Chain
{
TRL_ChainItem *First;
TRL_ChainItem *Last;
TRL_DataType Type;
}-
Firststores the pointer to the first ChainItem in the Chain -
Laststores the pointer to the last ChainItem in the Chain -
Typestores the TRL_DataType of the Chain whether it be an Inbuilt C data type like an int or a float or a TRL_DataType of a structure like a TRL_Buffer or even a TRL_Chain.
NOTE: You can refer to the Include/Chain.h to know more about TRL_Chain's functions.
Frist, like any other Data Structure in TRL, you will need to create it.
There are two ways to do it. One creates the TRL_Chain in the heap and another creates it in the stack.
NOTE: Creating it in the stack doesn't mean it will create the whole Chain in the stack. But instead it will create the TRL_Chain in the stack but every TRL_ChainItem will be created in the heap no matter what method you use.
TRL_Chain chain = TRL_Chain_Create(TRL_DataType);This will create a TRL_Chain in the Stack and return the copy of that Chain.
In the parameter, you will only need to pass what data type you want the chain to use.
TRL_Chain *chain = TRL_Chain_CreatePointer(TRL_DataType);It's the same as the normal Create function for Chain but it will create the TRL_Chain in heap.
Most of functions related to the TRL_Chain have one thing in common like all the other TRL data structures.
And that is, it will take what data structure you are modifying.
You will understand once you look at all the functions.
This function will delete all the elements of a Chain and its Items (ChainItems).
Yes, you have to handle the deletion of the actual data structure yourself. TRL only handles the creation and deletion of the elements in the Chain. It doesn't handle Garbage Collection.
Note: If you dont have any elements in your Chain because you either didn't create any or deleted all of them, then you technically don't need to call the Destroy function but it is recomended to do so.
-
TRL_Chain*The chain you want to destroy
Example:
TRL_Chain_Destroy(&chain);It will take the parameter of the TRL_Chain you wanna delete and free all the elements.
IMPORTANT: If you create the TRL_Chain in the heap with TRL_Chain_CreatePointer then you will need to manually free() that Chain after calling the TRL_Chain_Destroy.
This function is responsible to insert a ChainItem into the back of the Chain.\
-
TRL_Chain*The chain you want to insert the element into. -
void*The data you want the chain item to have.
-
TRL_ChainItem*The ChainItem that was just created.
Example:
TRL_Chain_InsertBack(&chain, &(int){69});This function will push the value 69 into the chain that is provided.
Like TRL_Chain_InsertBack, this function is responsible to add a ChainItem. But instead of adding it to the back of the Chain, it will add it to the front.
-
TRL_Chain*The chain you want to insert the element into. -
void*The data you want the chain item to have.
-
TRL_ChainItem*The ChainItem that was just created.
Example:
TRL_Chain_InsertFront(&chain, &(int){96});This function inserts a ChainItem after a given location of a ChainItem.
-
TRL_Chain*The chain you want to insert in -
TRL_ChainItem*The ChainItem you want to insert after -
void*The data of the ChainItem you are creating.
-
TRL_ChainItem*The ChainItem that was just created.
Example:
TRL_Chain_InsertAfter(&chain, atChainItem, &(int){31});This function is just like TRL_Chain_InsertAfter but instead of inserting after a given location of a ChainItem it inserts before that location.
-
TRL_Chain*The chain you want to insert in -
TRL_ChainItem*The ChainItem you want to insert after -
void*The data of the ChainItem you are creating.
-
TRL_ChainItem*The ChainItem that was just created.
Example:
TRL_Chain_InsertBefore(&chain, atChainItem, &(int){13});This function will search the whole Chain that was provideed and checks if there is a ChainItem containing the specified value.
-
TRL_Chain*The chain you want to search in -
void*The value you want to search
-
TRL_ChainItem*With the address of the ChainItem containing the given value
-
TRL_ChainItem*With NULL
Example:
TRL_ChainItem* chainItem = TRL_Chain_GetItemWith(chain, &(int){69});This function is responsible for removing a ChainItem at the back of the Chain
-
TRL_Chain*The chain you want to remove from
Example:
TRL_Chain_RemoveBack(&chain);This function is like TRL_Chain_RemoveBack but instead of removing an item from the back of the Chain, it will remove an item from the front of the Chain.
-
TRL_Chain*The chain you want to remove from
Example:
TRL_Chain_RemoveFront(&chain);This function is responsible to remove a specified ChainItem from a Chain
-
TRL_Chain*The chain you want to remove from -
TRL_ChainItem*The item you want to remove
Example:
TRL_Chain_RemoveAt(chain, item);NOTE:
In the examples of the functions, you will see that we passed a & (reference) of a TRL_Chain. This is because the functions take the memory address of the chain they want to modify.
If you created a ChainPointer, you shouldn't pass it as a & (reference) as it will pass a ** (double pointer) instead of a * (single pointer).