/** * @file stack.h * @brief Dynamic stack of long integers, using realloc for growth. * @note Does not include to avoid conflicting with stack_t from POSIX. */ #ifndef STACK_H #define STACK_H #include #include /** * @brief Forward declaration of a non-derivable class Stack. * */ typedef struct _stack_t stack_t; /** * @brief Constructs a stack with default initial capacity. * * @return A newly allocated stack. */ stack_t* stack_build_default(void); /** * @brief Destroys a stack and frees all allocated memory. * * @param self The stack (can be NULL). */ void stack_destroy(stack_t *self); /** * @brief Returns the number of elements currently in the stack. * * @param self The stack. * @pre self != NULL. * @return The size of the stack. */ size_t stack_size(const stack_t *const self); /** * @brief Returns the top element of the stack. * * @param self The stack. * @pre self != NULL && stack_size(self) > 0. * @return The value at the top of the stack. */ long stack_top(const stack_t *const self); /** * @brief Removes and discards the top element from the stack. * * @param self The stack. * @pre self != NULL && stack_size(self) > 0. */ void stack_pop(stack_t *const self); /** * @brief Pushes a value on top of the stack, growing if necessary. * * @param self The stack. * @param value The value to push. * @pre self != NULL. * @note Allocations are assumed to never fail. */ void stack_push(stack_t *const self, const long value); /** * @brief Tests whether the stack is empty. * * @param self The stack. * @pre self != NULL. * @return true if size == 0, false otherwise. */ bool stack_empty(const stack_t *const self); /** * @brief Empties the stack and resets its size to 0. * * @param self The stack. * @pre self != NULL. * @note Does not deallocate the internal array; capacity is retained. */ void stack_clear(stack_t *const self); #endif /* STACK_H */