/* stringHistory.h */

#ifndef STRING_HISTORY_H
#define STRING_HISTORY_H

#include <stdio.h>
#include <string.h>
#include <stddef.h>
#include <malloc.h>


/*
 * StringHistory - Data structure to store strings in a first-in
 * first-out manner. The string history has to be constructed with
 * a maxStringCount indicating the maximum number of strings that can
 * be stored.
 * The structure is fully dynamic.
 */
typedef struct _StringHistory {
  int nextStringCount;         // holds next index of pointer to char array
  int maxStringCount;          // holds maximum amount of char arrays
  char **string;               // pointer to pointer array to char arrays
} StringHistory;



// Prototype. Function must be implemented in application context.
void onErrorOutOfMemory();

// Prototype. Function must be implemented in application context.
void onNullPointer();


/* Create an empty string history on the heap.
 * !! Constraint:            maxStringCount >= 2, not enforced,
 *                            not tested
 * Params:
 *   int maxStringCount      the maximum number of strings
 *                            in this queue
 * Return:
 *   void
 */
StringHistory *createStringHistory(int maxStringCount);


/* Empty the string history.
 * Params:
 *   StringHistory *strHist  pointer to string history
 * Return:
 *   void
 */
void clearStringHistory(StringHistory *strHist);


/* Add a string to the string history.
 * Params:
 *   StringHistory *strHist  pointer to string history
 *   char *str               pointer to string to be added
 * Return:
 *   int                     true if successful, else false with
 *                            history unchanged
 */
int addStringHistory(StringHistory *strHist, char *str);


/* Set the new maxStringCount of the string history. If necessary
 * discard oldest strings.
 * !! Constraint:            maxStringCount >= 2, not enforced,
 *                            not tested
 * Params:
 *   StringHistory *strHist  pointer to string history
 *   int maxStringCount      new maximum number of strings in this queue
 * Return:
 *   void
 */
void setStringCount(StringHistory *strHist, int maxStringCount);


/* Release heap memory used by the string history.
 * Params:
 *   StringHistory *strHist  pointer to string history
 * Return:
 *   void
 */
void deleteStringHistory(StringHistory *strHist);


/* Clone the string history. Perform a deep copy on the heap.
 * Params:
 *   StringHistory *strHist  pointer to source string history
 * Return:
 *   StringHistory *         pointer to new string history
 */
StringHistory *cloneStringHistory(StringHistory *strHist);



/*
 * Print all the strings in the history to stdout, the first line
 * designating the oldest entry, the last line the youngest.
 * *strHist         - pointer to string history
 */
void printStringHistory(StringHistory *strHist);

#endif