Implement linked list data structure.

include/ll.h

@@ -0,0 +1,113 @@
+#ifndef LIBDS_LL_HEADER
+#define LIBDS_LL_HEADER
+
+#include "libds.h"
+
+/**
+ * A simple linked list node, doubly-linked.
+ */
+struct ll_node_s {
+    struct ll_node_s* next;
+    struct ll_node_s* prev;
+    void* data;
+};
+
+/**
+ * A linked list struct, containing pointers to the head and tail node.
+ */
+struct ll_s {
+    struct ll_node_s* head;
+    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);
+
+
+#endif