/*
 * stack.h - Implementación básica de Pila (Stack)
 *
 * Inspirado en "Data Structures and Algorithms Made Easy"
 * por Narasimha Karumanchi.
 *
 * Define un TAD de pila (LIFO - Last In, First Out) con
 * operaciones fundamentales y versiones recursivas
 * para fines didácticos.
 */

#ifndef STACK_H
#define STACK_H

#include <stdbool.h>

/* ===== ESTRUCTURA DE NODO ===== */
typedef struct _stack_node {
  int data;
  struct _stack_node *next;
} StackNode;

/* ===== CREACIÓN ===== */

/* Crea un nuevo nodo con el dato especificado */
StackNode *create_stack_node(int data);

/* ===== INSERCIÓN ===== */

/* Inserta un elemento en el tope (push, iterativo).
 * Retorna el nuevo top de la pila. */
StackNode *push(StackNode *top, int data);

/* ===== ELIMINACIÓN ===== */

/* Elimina el elemento en el tope y lo guarda en *data (iterativo).
 * Retorna el nuevo top, o NULL si la pila estaba vacía. */
StackNode *pop(StackNode *top, int *data);

/* ===== CONSULTA ===== */

/* Devuelve el valor del tope sin eliminarlo.
 * Retorna true si tuvo éxito, false si la pila está vacía. */
bool peek_stack(StackNode *top, int *data);

/* Verifica si la pila está vacía */
bool is_empty_stack(StackNode *top);

/* ===== TAMAÑO ===== */

/* Devuelve el número de elementos en la pila (iterativo) */
int size_stack(StackNode *top);
/* Devuelve el número de elementos en la pila (recursivo) */
int size_stack_rec(StackNode *top);

/* ===== DESTRUCCIÓN ===== */

/* Libera toda la memoria de la pila (iterativo) */
void destroy_stack(StackNode *top);
/* Libera toda la memoria de la pila (recursivo) */
void destroy_stack_rec(StackNode *top);

/* ===== IMPRESIÓN ===== */

/* Imprime los elementos de la pila de top a bottom (iterativo) */
void print_stack(StackNode *top);
/* Imprime los elementos de la pila de top a bottom (recursivo) */
void print_stack_rec(StackNode *top);
/* Imprime los elementos de la pila en orden inverso (bottom a top, recursivo)
 */
void print_stack_inverso_rec(StackNode *top);

/* ===== OPERACIONES AVANZADAS ===== */

/* Invierte la pila (recursivo).
 * Retorna el nuevo top de la pila. */
StackNode *invert_stack_rec(StackNode *top);

#endif // STACK_H