/*----------------------------------------------------------
 *				HTBLA-Leonding / Class: <your class>
 * ---------------------------------------------------------
 * Exercise Number: S03
 * Title:			Stack Inteface
 * Author:			Marc Tismonar
 * ----------------------------------------------------------
 * Description:
 * The declaration of a stack abstract data type.
 * ----------------------------------------------------------
 */

/** The type of the integer stack: IntStack */
typedef struct IntStackData* IntStack;

/**
 * Obtains ('creates') and provides a 'new' stack instance.
 * Any stack obtained via this function MUST be released using
 * function `release_stack()`.
 * 
 * Note: This function does not make any assumptions 
 * about how stack components, esp. nodes, are allocated.
 * 
 * @return IntStack The stack instance or 0, if no stack could by instantiated.
 */
IntStack stack_obtain();

/**
 * Releases a stack that was obtained earlier via function `obtain_stack`.
 * Released stacks MUST NOT be used anymore.
 * 
 * Note: The implementation of this function does not make any assumptions
 * about the allocation method of stack elements, but MUST match the implementation
 * of function `obtain_stack` as its inverse function.
 * 
 * @param p_stack The pointer to the stack to release. The value of the pointer
 * is set to 0, if the stack was successfully released, otherwise it is left untouched.
 */
IntStack stack_release(IntStack* p_stack);

/**
 * Determines whether or not the given stack is valid.
 * 
 * @param stack The stack to evaluate.
 * @return `True` if the stack is valid, false otherwise.
 */
bool stack_is_valid(IntStack stack);

/**
 * Determines whether or not the stack contains at least one item.
 * 
 * @param stack The stack to evaluate.
 * @return `False` if the stack contains one or more items, `true` otherwise.
 */
bool stack_is_empty(IntStack stack);

/**
 * Provides the number of values stored in the stack.
 * 
 * @param stack The stack to evaluate.
 * @return The number of values the stack contains.
 */
int stack_get_size(IntStack stack);

/**
 * Clears the given stack by removing all values from the stack.
 * 
 * @param stack The stack to clear.
 */
void stack_clear(IntStack stack);

/**
 * Inserts the given value to the stack.
 * 
 * @param stack The stack to which the value shall be appended.
 * @param value The value to append to the stack.
 */
void stack_push(IntStack stack, int value);

/**
 * Provides the value that 'pop' would provided but WITHOUT removing 
 * this value from the stack.
 * 
 * @param stack The stack from which the value shall be peeked.
 * @return The next value or 0, if the stack is empty.
 */
int stack_peek(IntStack stack);

/**
 * Provides AND removes the top-most value from the stack.
 * 
 * @param stack The stack from which the value be removed shall be returned.
 * @return The value or 0, if the stack is empty.
 */
int stack_pop(IntStack stack);