/*
 * list.h
 * A package for managing doubly-linked lists.
 */

/* Representation of a list element: */
struct _Element
{
  struct _Element  *p_prev;    /* Points to the previous element
                                 (or NULL in case of the list head). */
  double           value;      /* The stored value. */
  struct _Element  *p_next;    /* Points to the next element
                                 (or NULL in case of the list tail). */
};

typedef struct _Element Element;

/* Representation of a doubly-linked list: */
struct _List
{
  Element          *p_head;    /* Points to the list head
                                 (or NULL if the list is empty). */
  Element          *p_tail;    /* Points to the list tail
                                 (or NULL if the list is empty). */
  int              size;       /* The list size. */
};

typedef struct _List List;

/* ------------------------------------------------------------------------
 * Function: list_init
 * Purpose:  Initialize a doubly-linked list.
 * Returns:  A pointer to an allocated list.
 *           Note that this pointer should eventually be freed using 
 *           list_reset() and then free().
 */
List *list_init ();

/* ------------------------------------------------------------------------
 * Function: list_prepend
 * Purpose:  Insert a value as the list head.
 * Input:    p_list - The list.
 *           x      - The inserted value.
 * Returns:  Nothing.
 */
void list_prepend (List *p_list, double x);

/* ------------------------------------------------------------------------
 * Function: list_append
 * Purpose:  Insert a value as the list tail.
 * Input:    p_list - The list.
 *           x      - The inserted value.
 * Returns:  Nothing.
 */
void list_append (List *p_list, double x);

/* ------------------------------------------------------------------------
 * Function: list_find
 * Purpose:  Find a value in the list.
 * Input:    p_list - The list.
 *           x      - The queried value.
 * Returns:  A pointer to the list element that contains the queried value,
 *           or NULL if the value is not found in the list.
 */
const Element *list_find (const List *p_list, double x);

/* ------------------------------------------------------------------------
 * Function: list_delete
 * Purpose:  Delete a value from a list.
 * Input:    p_list - The list.
 *           x      - The value to be deleted.
 * Returns:  Non-zero in case the value was successfully deleted,
 *           or 0 if the value is not found in the list.
 */
int list_delete (List *p_list, double x);

/* ------------------------------------------------------------------------
 * Function: list_pop_first
 * Purpose:  Pop the first value from a list (and delete it).
 *           The list must not be empty.
 * Input:    p_list - The list.
 * Returns:  The value stored at the first element.
 */
double list_pop_first (List *p_list);

/* ------------------------------------------------------------------------
 * Function: list_pop_last
 * Purpose:  Pop the last value from a list (and delete it).
 *           The list must not be empty.
 * Input:    p_list - The list.
 * Returns:  The value stored at the last element.
 */
double list_pop_last (List *p_list);

/* ------------------------------------------------------------------------
 * Function: list_reset
 * Purpose:  Delete all objects from a list.
 * Input:    p_list - The list.
 * Returns:  Nothing.
 */
void list_reset (List *p_list);