#ifndef STRINGUTILSPREP
#define STRINGUTILSPREP

// header files
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <math.h>
#include <stdbool.h>
#include "StandardConstants.h"

// data structures

// function prototypes

/*
Name: catString
Process: concatenates two strings
Function input/parameters: c-style string (char *)
Function output/parameters: c-style string (char *)
Function output/returned: NONE
Device input/---: NONE
Device output/---: NONE
Dependencies: getStringLength
*/
void catString(char *outString, const char *inString);

/*
Name: compareString
Process: compares two strings as follows:
         - if left string is alphabetically greater than the right string,
         returns value greater than zero
         - if left string is alphabetically less than the right string,
         returns value less than zero
         - if strings are alphabetically equal but one is longer,
           longer one is greater
         - otherwise, returns zero
Function input/parameters: c-style strings (char *) [first and second/left&right]
Function output/parameters: NONE
Function output/returned: results as specfifed above (int)
Device input/---: NONE
Device output/---: NONE
Dependencies: getStringLength
*/
int compareString(const char *firstString, const char *secondString);

/*
Name: copyString
Process: copies string into new string variable, overwrites destination.
Function input/parameters: c-style string (char *)
Function output/parameters: c-style string (char *)
Function output/returned: NONE
Device input/---: NONE
Device output/---: NONE
Dependencies: getStringLength
*/
void copyString(char *outString, const char *inString);

/*
Name: getStringLength
Process: gets length of string from start to NULL_CHAR ('\0')
Function input/parameters: c-style string (char *)
Function output/parameters: NONE
Function output/returned: length of string (int)
Device input/---: NONE
Device output/---: NONE
Dependencies: included by standard libraries
*/
int getStringLength(const char *stringIn);

/*
Name: getSubString
Process: captures sub string within larger string
         between two inclusive indices.
         returns empty string if either index is out of range,
         assumes enough memory in dest string
Function input/parameters: c-style string (char *)
                           start and end indices (int)
Function output/parameters: c-style destination string (char *)
Function output/returned: NONE
Device input/---: NONE
Device output/---: NONE
Dependencies: getStringLength, malloc, copyString, free
*/
void getSubString(char *destStr, const char *sourceStr,
                  int startIndex, int endIndex);

/*
Name: findSubString
Process: linear search for given substring within another string
Function input/parameters: c-style test string (char *),
                           c-style source string (char *)
Function output/parameters: NONE
Function output/returned: index of found substring, or
                          SUBSTRING_NOT_FOUND constant
                          if string not found
Device input/---: NONE
Device output/---: NONE
Dependencies: getStringLength
*/
int findSubString();

/*
Name: strToLowerCase
Process: iterates through string, sets any uppercase letter to lowercase
         equivalent, does not affect any letter with an upper/lower diff.
Function input/parameters: c-style source string (char *)
Function output/parameters: c-style dest string (char *)
Function output/returned: NONE
Device input/---: NONE
Device output/---: NONE
Dependencies: toLowerCase
*/
void strToLowerCase();

/*
Name: toLowerCase
Process: sets character to lowercase letter if uppercase letter,
         returns character
Function input/parameters: character input (char)
Function output/parameters: NONE
Function output/returned: character output (char)
Device input/---: NONE
Device output/---: NONE
Dependencies: none
*/
char toLowerCase();

/*
Name: getStringToDelimiter
Process: captures a string from the input stream to a specified delimiter.
         will consume the delimiter.
Function input/parameters: input stream (FILE *),
                           stops at specified character
Function output/parameters: c-style string (char *)
Function output/returned: success of operation (bool)
Device input/---: NONE
Device output/---: NONE
Dependencies: getStringConstrained
*/
bool getStringToDelimiter(FILE *inStream, char delimiter, char *capString);

/*
Name: getStringConstrained
Process: captures a string from the file stream with various constraints
Function input/parameters: input stream (FILE *),
                           clears leading non printable (bool),
                           clears leading space (bool),
                           stops at non printable (bool),
                           stops at specified delimiter (char)
                           will consume the delimiter.
Function output/parameters: c-style string (char *)
Function output/returned: success of operation (bool)
Device input/---: NONE
Device output/---: NONE
Dependencies: fgetc
*/
bool getStringConstrained(FILE *inStream, bool clearLeadingNonPrintable,
                          bool clearLeadingSpace, bool stopAtNonPrintable,
                          char delimiter, char *capString);

/*
Name: getStringToLineEnd
Process: captures a string from the input stream to the end of the line
Function input/parameters: input file stream (FILE *)
Function output/parameters: c-style string (char *)
Function output/returned: success of operation (bool)
Device input/---: NONE
Device output/---: NONE
Dependencies: getStringConstrained
*/
bool getStringToLineEnd(FILE *inStream, char *capString);

#endif // STRINGUTILSPREP