/* stringlist.h
 *
 * A header file for stringlist.c
 *
 * AUTHORS:
 *
 * Rackham Hoke and Ashfaqur Rahman
 */

/* Make sure definitions are declared only once. */
#ifndef _STRINGLIST_H_
#define _STRINGLIST_H_


/* Define a type for a pointer to a linked list */
typedef struct stringList stringList;

/* The maximum length of a string to be stored in a node. */
#define MAX_VALUE_LENGTH 256


/*******************************************************/
/* FUNCTION DECLARATIONS (implemented in stringlist.c) */
/*******************************************************/


/* Creates an empty linked list.
 * Preconditions: none.
 * Postconditions: memory allocated for the returned list.
 * Problems: none.
 * Parameters: none.
 * Return: a pointer to a new linked list,
 *   NULL if memory allocation fails.
 */
stringList* newList();


/* Adds a node with the given value to the front of the given
 * list.
 * Preconditions: value is no longer than MAX_VALUE_LENGTH,
 *   list has been initialized.
 * Postconditions: memory allocated for the returned node,
 *   node added at front of the list.  If the list was empty
 *   previously, the new node becomes the current node.
 * Problems: none.
 * Parameters:
 *   value - the string value to place in the node.
 * Return: 1 if node was added successfully, 0 if node creation fails.
 */
int addToFront(stringList* list, char* value);


/* Adds a node with the given value to the end of the given
 * list.
 * Preconditions: value is no longer than MAX_VALUE_LENGTH,
 *   list has been initialized.
 * Postconditions: memory allocated for the returned node,
 *   node appended to the list. If the list was empty
 *   previously, the new node becomes the current node.
 * Problems: none.
 * Parameters:
 *   value - the string value to place in the node.
 * Return: 1 if node was added successfully, 0 if node creation fails.
 */
int addToEnd(stringList* list, char* value);


/* Concatenates two doubly linked lists.
 * Preconditions: listA and listB are handles to initialized lists.
 * Postconditions: listB is appended to listA,
 *   both listA and listB point the concatenated list.
 * Problems: none.
 * Parameters:
 *   listA - handle to the list to place at the beginning.
 *   listB - handle to the list to place at the end.
 * Return: nothing.
 */
void concatenateLists(stringList** listA, stringList** listB);


/* Outputs the values of the nodes in the given list to screen,
 * comma-separated, from front to end.
 * Preconditions: list has been initialized.
 * Postconditions: list is output on screen.
 * Problems: none.
 * Parameters:
 *   list - the list to output.
 * Return: nothing.
*/
void listToScreen(stringList* list);


/* Outputs the values of the nodes in the given list to screen,
 * comma-separated, from end to front.
 * Preconditions: list has been initialized.
 * Postconditions: list is output on screen.
 * Problems: none.
 * Parameters:
 *   list - the list to output.
 * Return: nothing.
 */
void listToScreenReversed(stringList* list);


/* Deletes the current node in the given list.
 * Preconditions: list has been initialized.
 * Postconditions: node is removed from the list and freed from
 *   memory, current is advanced if not already NULL (becomes
 *   NULL if the node deleted was the end node).
 * Problems: none.
 * Parameters:
 *   list - the list to perform the deletion on.
 * Return: 0 if current is NULL, 1 for success.
 */
int deleteCurrent(stringList* list);


/* Quicksorts a doubly linked list.
 * Preconditions: list has been initialized.
 * Postconditions: list is sorted.
 * Problems: none.
 * Parameters:
 *   list - the list to sort.
 * Return: 0 for abnormal termination (problem creating lists),
 *   1 for success.
 */
int quicksortList(stringList* list);

/* Tells if the given list is empty.
 * Preconditions: list has been initialized.
 * Postconditions: none.
 * Problems: none.
 * Parameters:
 *   list - the list to check.
 * Return: true if empty, false otherwise.
 */
int isEmpty(stringList* list);


/* Advances the current node in the given list.
 * Preconditions: list has been initialized.
 * Postconditions: current has been advanced, if possible.
 * Problems: none.
 * Parameters:
 *   list - the list to advance in.
 * Return: 1 if list was advanced, 0 otherwise.
 */
int moveNext(stringList* list);


/* Moves current to its previous node in the given list.
 * Preconditions: list has been initialized.
 * Postconditions: current has been moved back, if possible.
 * Problems: none.
 * Parameters:
 *   list - the list to move back in.
 * Return: 1 if list was moved back, 0 otherwise.
 */
int moveBack(stringList* list);


/* Tells if the current node in a list is the end node.
 * Preconditions: list has been initialized.
 * Postconditions: none.
 * Problems: none.
 * Parameters:
 *   list - the list whose current node to check.
 * Return: 1 if the current node is the end node, 0 otherwise.
 */
int atEnd(stringList* list);


/* Tells if the current node in a list is the front node.
 * Preconditions: list has been initialized.
 * Postconditions: none.
 * Problems: none.
 * Parameters:
 *   list - the list whose current node to check.
 * Return: 1 if the current node is the front node, 0 otherwise.
 */
int atFront(stringList* list);


/* Reads a newline-separated list of strings from a file
 * with the given name.
 * Preconditions: the file exists, there is no newline after
 *   the last element listed in the file (would give an empty
 *   node).
 * Postconditions: memory allocated for the returned list.
 * Problems: none.
 * Parameters:
 *   fileName - the name of the file to get the list from.
 * Return: the list read from the file, or NULL if the file
 *   fails to open, list creation fails, or node creation fails.
 */
stringList* listFromFile(char* fileName);


/* Writes the given list to the file with the given name, with
 * node values separated by newlines.
 * Preconditions: file exists, list has been initialized.
 * Postconditions: previous file data is lost, list is written.
 * Problems: none.
 * Parameters:
 *   list - the list to write to file.
 *   fileName - the name of the file to write to.
 * Return: 1 for succcess, 0 for failure to open or write file.
 */
int listToFile(stringList* list,char* fileName);


/* Frees a list and all of its nodes from memory.
 * Preconditions: list has been initialized.
 * Postconditions: the list and all of its nodes are freed.
 * Problems: none.
 * Parameters:
 *   list - the list to free.
 * Return: nothing.
 */
void freeList(stringList* list);


/* Returns the value of the current node in the list.
 * Preconditions: list has been initialized.
 * Postconditions: none.
 * Problems: none.
 * Parameters:
 *   list - the list whose current to check.
 * Return: the value contained in the current node, or NULL
 *   if the current node is NULL.
 */
char* currentValue(stringList* list);


/* Reverses a doubly linked list.
 * Preconditions: list has been initialized.
 * Postconditions: list is reversed.
 * Problems: none.
 * Parameters:
 *   list - the list to reverse.
 * Return: nothing.
 */
void reverseList(stringList* list);


/* Resets the current node in the given list to the front
 * of the list.
 * Preconditions: list has been initialized.
 * Postconditions: current points to front of list.
 * Problems: none.
 * Parameters:
 *   list - the list whose current to reset.
 * Return: nothing.
 */
void resetCurrent(stringList* list);


#endif