/**
 * list.h 
 *   Wrapped linked lists.
 */

#ifndef __LIST_H__
#define __LIST_H__


// +-------------------+----------------------------------------------
// | Primary Functions |
// +-------------------+

/**
 * Procedure:
 *   new_list
 * Parameters:
 *   [None]
 * Purpose:
 *   Create a new, empty list.
 * Produces:
 *   lst, a list
 * Problems:
 *   If no memory is available, returns NULL.
 */
struct list *new_list ();

/**
 * Procedure:
 *   list_first
 * Parameters:
 *   lst, a pointer to a nonempty list.
 * Purpose:
 *   Find the first element in lst
 * Produces:
 *   first, a string
 * Preconditions:
 *   [No additional.]
 * Postconditions:
 *   first is the first element in lst.
 */
char *list_first (struct list *lst);

/**
 * Procedure:
 *   list_last
 * Parameters:
 *   lst, a pointer to a nonempty list.
 * Purpose:
 *   Find the last element in lst
 * Produces:
 *   last, a string
 * Preconditions:
 *   [No additional.]
 * Postconditions:
 *   last is the last element in lst.
 */
char *list_last (struct list *lst);

/**
 * Procedure:
 *   list_length
 * Parameters:
 *   lst, a pointer to a list.
 * Purpose:
 *   Find the length of the list given by lst.
 * Produces:
 *   length, an integer
 * Preconditions:
 *   [No additional]
 * Postconditions:
 *   length is the number of nodes in lst.
 */
int list_length (struct list *lst);

/**
 * Procedure:
 *   list_print
 * Parameters:
 *   lst, a pointer to a list
 *   fp, a file pointer
 * Purpose:
 *   Prints lst (in Scheme form!) to fp.
 * Produces:
 *   [Nothing; Called for the side effect.]
 * Preconditions:
 *   fp must be open for writing.
 * Postconditions:
 *   fp now contains a representation of lst.
 *   lst is unchanged.
 */
void list_print (struct list *lst, FILE *fp);

/** 
 * Procedure:
 *   list_append
 * Parameters:
 *   lst, a pointer to a list
 *   str, a string
 * Purpose:
 *   Adds str to the end of lst
 * Produces:
 *   ok, an integer
 * Preconditions:
 *   [No additional.]
 * Postconditions:
 *   If problems occurred, ok is 0
 *   Otherwise, ok is 1 and list_last (lst) = str
 */
int list_append (struct list *lst, char *str);

/** 
 * Procedure:
 *   list_prepend
 * Parameters:
 *   lst, a pointer to a list
 *   str, a string
 * Purpose:
 *   Adds str to the front of lst
 * Produces:
 *   ok, an integer
 * Preconditions:
 *   [No additional.]
 * Postconditions:
 *   If problems occurred, ok is 0
 *   Otherwise, ok is 1 and list_first (lst) = str
 */
int list_prepend (struct list *lst, char *str);

/**
 * Procedure:
 *   list_delete
 * Parameters:
 *   lst, a pointer to a list .
 *   str, a string
 * Purpose:
 *   Delete the first element in lst whose car is str.
 * Produces:
 *   success, an integer
 * Preconditions:
 *   str must appear in the list.
 * Postconditions:
 *   The list contains one fewer copy of str.
 */
int list_delete (struct list *lst, char *str);

/**
 * Procedure:
 *   list_contains
 * Parameters:
 *   lst, a pointer to a list
 *   str, a string
 * Purpose:
 *   Determine whether or not lst contains str.
 * Produces:
 *   contains, an integer (representing a Boolean).
 */
int list_contains (struct list *lst, char *str);

/**
 * Procedure:
 *   list_insert_after
 * Parameters:
 *   lst, a pointer to a list
 *   target, a string
 *   str, a string
 * Purpose:
 *   Insert str after target.
 * Produces:
  *  success, an integer
 * Preconditions:
 *   target is in lst.
 */
int list_insert_after (struct list *lst, char *target, char *str);

/**
 * Procedure:
 *   list_insert_before
 * Parameters:
 *   lst, a pointer to a list
 *   target, a string
 *   str, a string
 * Purpose:
 *   Insert str before target.
 * Produces:
  *  success, an integer
 * Preconditions:
 *   target is in lst.
 */
int list_insert_before (struct list *lst, char *target, char *str);

#endif // __LIST_H__