#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(const 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(const 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(const 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(const 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