list.h

#ifndef PRISM_INTERNAL_LIST_H
#define PRISM_INTERNAL_LIST_H
 
#include <stddef.h>
 
/*
 * This struct represents an abstract linked list that provides common
 * functionality. It is meant to be used any time a linked list is necessary to
 * store data.
 *
 * The linked list itself operates off a set of pointers. Because the pointers
 * are not necessarily sequential, they can be of any size. We use this fact to
 * allow the consumer of this linked list to extend the node struct to include
 * any data they want. This is done by using the pm_list_node_t as the first
 * member of the struct.
 *
 * For example, if we want to store a list of integers, we can do the following:
 *
 * ```c
 * typedef struct {
 *     pm_list_node_t node;
 *     int value;
 * } pm_int_node_t;
 *
 * pm_list_t list = { 0 };
 * pm_int_node_t *node = xmalloc(sizeof(pm_int_node_t));
 * node->value = 5;
 *
 * pm_list_append(&list, &node->node);
 * ```
 *
 * The pm_list_t struct is used to represent the overall linked list. It
 * contains a pointer to the head and tail of the list. This allows for easy
 * iteration and appending of new nodes.
 */
typedef struct pm_list_node {
    /* A pointer to the next node in the list. */
    struct pm_list_node *next;
} pm_list_node_t;
 
/*
 * This represents the overall linked list. It keeps a pointer to the head and
 * tail so that iteration is easy and pushing new nodes is easy.
 */
typedef struct {
    /* The size of the list. */
    size_t size;
 
    /* A pointer to the head of the list. */
    pm_list_node_t *head;
 
    /* A pointer to the tail of the list. */
    pm_list_node_t *tail;
} pm_list_t;
 
/* Returns the size of the list. */
size_t pm_list_size(pm_list_t *list);
 
/* Append a node to the given list. */
void pm_list_append(pm_list_t *list, pm_list_node_t *node);
 
#endif