libds/include/ll.h

136 lines
4.2 KiB
C

#ifndef LIBDS_LL_HEADER
#define LIBDS_LL_HEADER
#include "libds.h"
/**
* A simple linked list node, doubly-linked.
*/
struct ll_node_s {
/**
* The next node in the linked list
*/
struct ll_node_s* next;
/**
* The previous node in the linked list.
*/
struct ll_node_s* prev;
/**
* The data of the linked list node.
*/
void* data;
};
/**
* A linked list struct, containing pointers to the head and tail node.
*/
struct ll_s {
/**
* The head of the linked list.
*/
struct ll_node_s* head;
/**
* The tail of the linked list.
*/
struct ll_node_s* tail;
};
typedef struct ll_node_s ll_node;
typedef struct ll_s ll;
/**
* Initializes the list with default values.
* @param ll the linked list to initialize.
*/
void ll_init(ll* ll);
/**
* Frees the linked list and all underlying data.
* The stored data is left intact. Use ll_foreach to free
* the data if it is no longer used.
* @param ll
*/
void ll_free(ll* ll);
/**
* Adds an element to the end of the linked list.
* @param ll the linked list to add to
* @param data the data to add
* @return LIBDS_SUCCESS if all goes well, LIBDS_MALLOC if an allocation fails.
*/
libds_result ll_append(ll* ll, void* data);
/**
* Adds an element to the beginning of the linked list.
* @param ll the linked list to add to
* @param data the data to add
* @return LIBDS_SUCCESS if all goes well, LIBDS_MALLOC if an allocation fails.
*/
libds_result ll_prepend(ll* ll, void* data);
/**
* Removes an element from the list.
* @param ll the linked list from which to remove.
* @param data the data to remove.
*/
void ll_remove(ll* ll, void* data);
/**
* Runs through every element in the linked list, and compares it against the
* given data using the given comparison function. If the comparison function returns
* true, returns the element that was passed to it. If the comparison function returns
* true for no element, returns NULL.
* @param ll the linked list to iterate through.
* @param data the data to compare elements against
* @param compare the comparison function
* @return the first element that is matched by the comparison function, or NULL if none are matched.
*/
void* ll_find(ll* ll, void* data, compare_func compare);
/**
* Runs through every element in the linked list, and compares it against the
* given data using the given comparison function. If the comparison function returns
* true, calls the foreach function, passing it the element and the variable argument list.
* Stops if any foreach function returns a nonzero code.
* @param ll the linked list to perform the operation on
* @param data the data to pass the comparison function
* @param compare the comparison function operating on the data and each element in the list.
* @param foreach the function to be called on every element recognized by the comparison function
* @param ... variable arguments to be passed on to the foreach function
* @return 0 if all goes well, or the first nonzero code returned by foreach.
*/
int ll_foreach(ll* ll, void* data, compare_func compare, foreach_func foreach, ...);
/**
* Gets the element at the beginning of the linked list.
* @param ll the linked list to get the data from.
* @return the element at the beginning of the element, or NULL if there is none.
*/
void* ll_head(ll* ll);
/**
* Gets the element at the end of the linked list.
* @param ll the linked list to get the data from.
* @return the element at the end of the element, or NULL if there is none.
*/
void* ll_tail(ll* ll);
/**
* Removes the element at the beginning of the linked list,
* and returns it.
* @param ll the linked list to perform the operation on.
* @return the value removed from the beginning of the linked list, or NULL if there was none.
*/
void* ll_pophead(ll* ll);
/**
* Removes the element at the end of the linked list,
* and returns it.
* @param ll the linked list to perform the operation on.
* @return the value removed from the end of the linked list, or NULL if there was none.
*/
void* ll_poptail(ll* ll);
/**
* Removes all elements from the list, freeing the underlying memory
* but keeping the data intact,
* @param ll the linked list to clear.
*/
void ll_clear(ll* ll);
#endif