BNSLIb Core Data Structures

A core part of BNSLib is it's data structures. There are currently three data structures:

• DynamicArray
• Stack
• CircularBuffer

DynamicArray

DynamicArray is probably the most used datastructure in all of BNSLib. It is just like a normal array, except there is no defined size or object! In other words, you can define an array of "floats" or "stacks" or any structure with no size and have it grow over time. You can even have an array of a stack of arrays of a circular buffer (try to wrap your head around that!)

To setup DynamicArray by the following calls:
DynamicArray your_array;
DynamicArrayInit(your_array, float); // Create an array of floats
// DynamicArrayInit(your_array, int); // Create an array of integers
// DynamicArrayInit(your_array, Stack); // Create an array of stack structs

To add a new element to the array, use the following call:
float x = 5;
DynamicArray(&your_array, &x); // Use pointers. The & symbol takes a variable and returns the memory address of it
or
DynamicArrayAddEmpty(&your_array); // Adds a new float without defining the value

To set an existing element in the array, use the following call:
float x = 5;
DynamicArraySet(&your_array, 3, &x); // Sets the element at index 3 to x

To get an existing element in the array, use the following call:

float* pX;
pX = DynamicArrayGet(&your_array, 3); // Gets the element at index 3 to the pointer pX
float x = *pX // Convert the pointer to your value.

Why the use of pointers? When we use pointers, we don't need to know what type of variable that is being passed, only the fact it's a pointer to a memory location. When you initialize the array using DynamicArrayInit, there is a macro that figures out how big the struct is and allocates that much memory for each element in the array. This means any structure can be saved as a dynamicArray, you can even have a dynamicArray of dynamicArrays!

Stack

Stacks are useful in situations when you want elements to enter and exit an array in an order such that the first element entering the array is the last to be read. For instance, think of stacking cups. If you want to get the bottom cup, you have to remove all the cups above it first.

Stacks actually implement an DynamicArray, so the calls are very similar.
Stack your_stack;
StackInit(&your_stack, float); // A stack of floats

To push (add an element to the array), to pop (remove the top element and return it), or to peek (look at the top element without removing it):
float x1 = 123;
float x2 = 456;
StackPush(&your_stack, &x1); // Add 123 to the stack
StackPush(&your_stack, &x2); // Add 456 to the stack
float* y = StackPop(&your_array); // Remove top element
float z = *y; // z is set to 456
y = StackPeek(&your_array); // Look at the new top element
z = *y; // z is now set to 123

CircularBuffer

Circular buffer is similar to a Stack except the first element put into the array is the first to come out. This is a type of queue, except there is a set size

CircularBuffesr actually implement an DynamicArray, so the calls are very similar.
CircularBuffer your_buffer;
CircularBuffer Init(&your_buffer, float, 3); // A circular buffer of 3 floats

To add to the buffer or get the next object:
float x1 = 123;<br/ float x2 = 456;
CircularBufferAdd(&your_buffer, &x1); // Add 123 to the stack
CircularBufferAdd(&your_buffer, &x2); // Add 456 to the stack
float* y = CircularBufferGet(&your_buffer); // Remove the oldest element (123)
float z = *y; // z is set to 123
y = CircularBufferGet(&your_buffer); // Remove the oldest element (456)
z = *y; // z is set to 456