list.h

#ifndef SINGLY_LINKED_LIST_H
#define SINGLY_LINKED_LIST_H

#include <stddef.h> // For size_t

// Structure for a single node in the linked list
typedef struct Node {
    void *data;          // Pointer to the data stored in the node
    struct Node *next;   // Pointer to the next node in the list
} Node;

// Structure for the singly linked list with a sentinel node
typedef struct LinkedList {
    Node *head;      // Pointer to the sentinel node
    size_t size;         // Current number of actual data nodes in the list
} LinkedList;

// Function Prototypes

/**
 * @brief Initializes a new empty singly linked list with a sentinel node.
 * The sentinel node's data is always NULL and is not considered
 * part of the actual data elements.
 * @return A pointer to the newly created LinkedList structure, or NULL if
 * memory allocation fails.
 */
LinkedList *sll_create();

/**
 * @brief Frees all memory associated with the linked list, including
 * all nodes and the sentinel node. It does NOT free the data
 * pointed to by 'data' within each node.
 * @param list A pointer to the LinkedList to be destroyed.
 */
void sll_destroy(LinkedList *list);

/**
 * @brief Adds a new node to the front (after the sentinel) of the list.
 * @param list A pointer to the LinkedList.
 * @param data A pointer to the data to be stored in the new node.
 * @return 0 on success, -1 if memory allocation fails.
 */
int sll_add_front(LinkedList *list, void *data);

/**
 * @brief Adds a new node to the end of the list.
 * @param list A pointer to the LinkedList.
 * @param data A pointer to the data to be stored in the new node.
 * @return 0 on success, -1 if memory allocation fails.
 */
int sll_add_back(LinkedList *list, void *data);

/**
 * @brief Inserts a new node at a specific position (0-indexed).
 * If pos is 0, it behaves like sll_add_front.
 * If pos is list->size, it behaves like sll_add_back.
 * @param list A pointer to the LinkedList.
 * @param data A pointer to the data to be stored in the new node.
 * @param position The 0-indexed position where the node should be inserted.
 * @return 0 on success, -1 if memory allocation fails or position is out of bounds.
 */
int sll_insert_at(LinkedList *list, void *data, size_t position);

/**
 * @brief Removes the node at the front of the list (after the sentinel).
 * @param list A pointer to the LinkedList.
 * @return A pointer to the data of the removed node, or NULL if the list is empty.
 */
void *sll_remove_front(LinkedList *list);

/**
 * @brief Removes the node at the end of the list.
 * @param list A pointer to the LinkedList.
 * @return A pointer to the data of the removed node, or NULL if the list is empty.
 */
void *sll_remove_back(LinkedList *list);

/**
 * @brief Removes the node at a specific position (0-indexed).
 * @param list A pointer to the LinkedList.
 * @param position The 0-indexed position of the node to be removed.
 * @return A pointer to the data of the removed node, or NULL if the list is empty
 * or the position is out of bounds.
 */
void *sll_remove_at(LinkedList *list, size_t position);

/**
 * @brief Retrieves the data from the node at a specific position (0-indexed).
 * @param list A pointer to the LinkedList.
 * @param position The 0-indexed position of the node.
 * @return A pointer to the data of the node, or NULL if the position is out of bounds.
 */
void *sll_get_at(const LinkedList *list, size_t position);

/**
 * @brief Searches for a node containing specific data and returns its 0-indexed position.
 * @param list A pointer to the LinkedList.
 * @param data A pointer to the data to search for.
 * @param compare A function pointer used to compare two data pointers.
 * It should return 0 if the data are equal, non-zero otherwise.
 * @return The 0-indexed position of the first occurrence of the data, or -1 if not found.
 */
int sll_find(const LinkedList *list, const void *data, int (*compare)(const void *, const void *));

/**
 * @brief Gets the current number of actual data nodes in the list.
 * @param list A pointer to the LinkedList.
 * @return The number of nodes in the list.
 */
size_t sll_size(const LinkedList *list);

/**
 * @brief Checks if the linked list is empty (contains no actual data nodes).
 * @param list A pointer to the LinkedList.
 * @return 1 if the list is empty, 0 otherwise.
 */
int sll_is_empty(const LinkedList *list);

/**
 * @brief Prints the data of each node in the list.
 * Requires a print function pointer to handle generic data types.
 * @param list A pointer to the LinkedList.
 * @param print_func A function pointer that takes a void* data and prints it.
 */
void sll_print(const LinkedList *list, void (*print_func)(const void *));

#endif // SINGLY_LINKED_LIST_H