#ifndef STACK_H
#define STACK_H

// stack
typedef struct Stack Stack;

/*
 * stack_new: create a new stack
 * returns:
 * 	Stack * -> the created stack
 * 	NULL -> failed to allocate memory for stack
 */
Stack *stack_new(void);

/* stack_delete: free the stack, but don't free any buffer in any of it's */
void stack_delete(Stack *stack);

/*
 * stack_free: free the stack, each element is also freed accordingly using
 * 'free_data'
 * parameters:
 * 	stack (Stack *) -> stack to delete
 * 	free_data -> function that would free resources of each element in stack
 */
void stack_free(Stack *stack, void (*free_data)(void *data));

/*
 * stack_push: push element to top of stack
 * parameters:
 * 	stack (Stack *) -> stack to push data into
 * 	data (void *) -> data to push
 * returns:
 * 	void * -> the pushed data
 * 	NULL -> failure of allocating memory for new stack element
 */
void *stack_push(Stack *stack, void *data);

/* stack_pop: pop element from top of stack */
void *stack_pop(Stack *stack);

/* stack_get_size: get size of stack */
size_t stack_size(Stack *stack);

/*
 * stack_get_size: iterate over a stack top-to-bottom, running 'apply' on each
 * stack element
 * parameters:
 * 	stack (Stack *) -> stack to iterate over
 * 	apply -> function that would be passed each element in stack
 * returns:
 * 	void * -> sucess (pointer to stack)
 * 	NULL -> one of the executions of 'apply' returned NULL
 */
void *stack_iter(Stack *stack, void *(*apply)(void *data));

/*
 * stack_iter_reverse: iterate over a stack bottom-to-top, running 'apply' on
 * each stack element
 * parameters:
 * 	stack (Stack *) -> stack to iterate over
 * 	apply -> function that would be passed each element in stack
 * returns:
 * 	void * -> sucess (pointer to stack)
 * 	NULL -> one of the executions of 'apply' returned NULL
 */
void *stack_iter_reverse(Stack *stack, void *(*apply)(void *data));

#endif /* STACK_H */