58 lines
1.8 KiB
Plaintext
58 lines
1.8 KiB
Plaintext
.TL
|
|
stack.h
|
|
|
|
.AU
|
|
Wael Karram
|
|
|
|
.AB no
|
|
Documentation for stack.h
|
|
.AE
|
|
|
|
.DA
|
|
|
|
.LP
|
|
This header defines a stack (FIFO), with the prepoccessor variable STACK_H used as an include guard.
|
|
.br
|
|
Defines a single struct
|
|
.UL stack_t \0which
|
|
has the fields
|
|
.I "int size" \0and
|
|
.I "node_t *head" ,
|
|
the former of which refers to the stack's size, and the latter of which refers to the stack's head.
|
|
|
|
.LP
|
|
This header also includes the following headers:
|
|
.br
|
|
.I "stdlib.h" ,
|
|
.I "../nodes/single_node.h" .
|
|
|
|
.LP
|
|
This header defines the following constants:
|
|
.br
|
|
.I "INITIAL_STACK_SIZE" sets the initial stack size to 0.
|
|
.br
|
|
.I "PUSH_SUCCESS" sets the success code for a push to 1.
|
|
.br
|
|
.I "PUSH_FAIL" sets the failure code for a push to 0.
|
|
.br
|
|
.I "INVALID_SIZE" returned on invalid size given, evaluates to -1.
|
|
|
|
.LP
|
|
Function definitions, input and expected behavior:
|
|
.br
|
|
stack_t* initialize_stack() - This function initializes a new empty stack, returns NULL on failure.
|
|
.br
|
|
node_t* pop(stack_t *stack) - Pops the head of the stack, returns NULL on empty or NULL stack.
|
|
.br
|
|
const void* peek(stack_t *stack) - Peeks at the top of the stack, returns the stored value there without poLPing.
|
|
.br
|
|
int push(stack_t *stack, node_t *node) - Pushes a node into the top of the stack, fails on NULL input.
|
|
.br
|
|
int push_data(stack_t *stack, void *data) - Pushes a node into the top of the stack, fails on NULL stack or allocation error.
|
|
.br
|
|
int stack_size(stack_t *stack) - This function returns the stack's size, returns INVALID_SIZE on error or NULL stack.
|
|
.br
|
|
void free_stack(stack_t **stack) - This function frees a stack and sets the pointer (*stack) to NULL, doesn't touch the data.
|
|
.br
|
|
void free_stack_data(stack_t **stack, void (*free_function)(const void*)) - This function frees a stack and sets the pointer (*stack) to NULL, frees the data too, if free_function is NULL will use standard free() instead.
|