Stacks

A stack data structure is a so called LIFO (Last-In First-Out) structures. You can push values on a stack and the remove them again by popping them from the stack. The value that was pushed on the stack most recently is the first to be popped from it again. Stacks are often used when there are interrupts to handle, or when having recursive functions. The following functions exist for stacks:

ds_stack_create() Creates a new stack. The function returns an integer as an id that must be used in all other functions to access the particular stack. You can create multiple stacks.
ds_stack_destroy(id) Destroys the stack with the given id, freeing the memory used. Don't forget to call this function when you are ready with the structure.
ds_stack_clear(id) Clears the stack with the given id, removing all data from it but not destroying it.
ds_stack_copy(id,source) Copies the stack source into the stack with the given id.
ds_stack_size(id) Returns the number of values stored in the stack.
ds_stack_empty(id) Returns whether the stack is empty. This is the same as testing whether the size is 0.
ds_stack_push(id,val) Pushes the value on the stack.
ds_stack_pop(id) Returns the value on the top of the stack and removes it from the stack.
ds_stack_top(id) Returns the value on the top of the stack but does not remove it from the stack.
ds_stack_write(id) Turns the data structure into a string and returns this string. The string can then be used to e.g. save it to a file. This provides an easy mechanism for saving data structures.
ds_stack_read(id,str) Reads the data structure from the given string (as created by the previous call).