nesemu/utils/linked_list.h

//
// Created by william on 1/16/24.
//

#include <stdbool.h>

#ifndef NESEMULATOR_LINKED_LIST_H
#define NESEMULATOR_LINKED_LIST_H

typedef struct linked_list_node {
    struct linked_list_node *previous;
    struct linked_list_node *next;
    void *data;
} LinkedListNode;

typedef struct linked_list {
    bool circular;
    unsigned int size;
    LinkedListNode *head;
    LinkedListNode *end;
    LinkedListNode *current;
} LinkedList;

/**
 * Initializes a new linked list.
 *
 * @param circular If the list is circular, meaning that the last node is linked to the first node.
 * @return The linked list instance
 */
LinkedList linked_list_init(bool circular);

/**
 * Adds data to a linked list.
 *
 * @param list The linked list
 * @param data The data to add
 */
void linked_list_add(LinkedList *list, void *data);

/**
 * Gets the next node in the list.
 *
 * @param list The linked list
 * @return The next node in the list. Can be NULL if the list is empty or depleted.
 */
LinkedListNode *linked_list_next(LinkedList *list);

/**
 * Resets the position of the cursor to the head of the list.
 */
void linked_list_cursor_reset(LinkedList *list);

/**
 * Searches for data corresponding to a predicate.
 * The search will stop after reaching the first node matching the given predicate.
 *
 * @param list The list to search in
 * @param predicate The predicate to match the data
 * @param userdata Parameter to pass to the predicate
 * @return The first node in the list matching the predicate
 */
LinkedListNode *linked_list_get_if(LinkedList *list, bool(*predicate)(void *, void *), void *userdata);

/**
 * Searches for data with the smallest distance computed from a function.
 * The search will stop when a node increasing the distance is found. For this reason, the distance computing function should have a single minimum.
 *
 * @param list The list to search in
 * @param compute_distance The function to compute the distance of a node's data
 * @param userdata  Parameter to pass to the function
 * @return The node with the smallest distance
 */
LinkedListNode *linked_list_get_near(LinkedList *list, int(*compute_distance)(void *, void *), void *userdata);

/**
 * Deinitializes a linked list.
 *
 * @param list The list to deinitialize
 */
void linked_list_uninit(LinkedList *list);

#endif //NESEMULATOR_LINKED_LIST_H