/* File:    stringlist.h
 * Author:  Samuel A. Rebelsky
 * Version: 1.0 of February 2000
 *
 * Common information on a simple implementation of lists of strings.
 * Elements remain in the order in which they're specified.  Written 
 * as an example for CSC364 2000S.
 */

/***********
 * Headers *
 *****************************************************************/

#include <stdio.h>     /* Defines FILE */

/*************
 * Constants *
 *****************************************************************/

/* Yes, I know this is normally defind, but it doesn't hurt
 * to be careful.
 */
#ifndef NULL
#define NULL 0
#endif

/* The maximum number of characters in a string. */
#define MAXSTRING 256

/*********
 * Types *
 *****************************************************************/

/* Lists.  The implementation is purposefully hidden. */
typedef struct stringlist *stringlist;

/************************
 * Basic List Functions *
 *****************************************************************/

/* Add an element to the end of the list. 
 * Pre: The list has been initialized.
 * Post: Adds the element to the end of the list.
 *       Disturbs iteration.
 * Returns: 1 upon success and 0 upon failure.
 */
int addToEnd(stringlist stuff, char *value);

/* Add an element to the front of the list. 
 * Pre: The list has been initialized.
 * Post: Adds the element to the front of the list.
 *       Disturbs iteration.
 * Returns: 1 upon success and 0 upon failure.
 */
int addToFront(stringlist stuff, char *value);

/* Clear the list.
 * Pre: None.
 * Post: The list contains no elements.
 */
void clear(stringlist stuff);

/* Delete all copies of a pattern from the list.
 * Pre: The pattern is non-null.
 * Post: The list no longer contains copies of the pattern.
 */
void deleteAll(stringlist stuff, char *pattern);

/* Free the space allocated to a list.   Note that after you 
 * free a list, the pointer still points somewhere in (now-freed)
 * memory, so you should reset it to NULL.
 * Pre: None
 * Post: The memory associated with the list has been freed.
 */
void freeList(stringlist stuff);

/* Create a new, empty list.
 * Pre: None
 * Post: Returns a pointer to a list.  Returns NULL if 
 *       insufficient memory is available.
 */
stringlist newList();

/* Get the next uniterated element of the list.
 * Pre: The list has not changed since the last call to reset().
 * Post: Returns another uniterated element.  Returns null if no
 *       uniterated elements. remain.
 */
char *nextElement(stringlist stuff);

/* Reset iteration to the beginning of the list.
 * Pre: None
 * Post: The list cursor has returned to the beginning.  The
 *       next call to nextElement will return the first element
 *       of the list (providing the list has an element).
 */
void reset(stringlist stuff);

/**********************
 * List I/O Functions *
 *****************************************************************/

/* Dump a list to a file.
 * Pre: The list has been initialized.
 *      The process has appropriate permissions to create the file.
 * Post: A copy of the list is now in the file, with one line
 *         per list entry. 
 *       The list has been iterated, so the current element may
 *         have changed.
 */
void dumpList(char *fname, stringlist stuff);

/* Print a list to a file or the screen.
 * Pre: The list has been initialized.
 *      The FILE* is writable.
 * Post: A copy of the list has been written to the appropriate
 *         destination, wtih one line per list entry.
 *       The list has been iterated, so the current element may
 *         have changed.
 */
void printList(FILE *dest, stringlist stuff);

/* Read a list from a file.
 * Pre: The file was created with dumpList.
 *      The file is readable.
 *      No line contains more than MAXSTRING characters.
 * Post: Returns a new list, with each entry in the list corresponding
 *       to one line of the file.  Returns null if it had some difficulty.
 */
stringlist readList(char *fname);