#ifndef __STRING_UTILS_H__
#define __STRING_UTILS_H__

/**
 * string-utils.h
 *   Declarations for a variety of useful and fun string utilities.
 */


// +------------------+-----------------------------------------------
// | Fun with Strings |
// +------------------+

/**
 * Procedure:
 *   the_name_game
 * Parameters:
 *   name, a string
 * Purpose:
 *   Print the lyrics to one verse of the name game.
 * Produces:
 *   [Nothing; called for the side effect.]
 * Preconditions:
 *   name is not empty.
 * Postconditions:
 *   A verse of the name game has been printed to standard output.
 * Practica:
 *   the_name_game ("Nick");
 *     Nick!
 *     Nick, Nick bo Bick Bonana fanna fo Fick
 *     Fee fy mo Mick, Nick
 *   the_name_game ("Shirley");
 *     Shirley!
 *     Shirley, Shirley bo Bhirley Bonana fanna fo Fhirley
 *     Fee fy mo Mhirley, Shirley!
 *   the_name_game ("Akshay");
 *     Akshay!
 *     Akshay, Akshay bo Bakshay Bonaa fanna fo Fakshay
 *     Fee fy mo Makshay, Akshay!
 * Props:
 *   Shirley Ellis performed the best-known version of the name game.
 *   She also co-wrote the song.
 * Problems:
 *   (1) But if the first two letters are ever the same,
 *       You drop them both and say the name like
 *       Bob, Bob drop the B's Bo ob
 *       For Fred, Fred drop the F's Fo red
 *       For Mary, Mary drop the M's Mo ary
 *       That's the only rule that is contrary.
 *   (2) Ms. Ellis is inconsistent on the dropping of letters.  For
 *       example, she drops only the F in Fred, but both the S and h
 *       in Shirley.  We drop only the first letter
 *       
 */
void the_name_game (char *name);

/**
 * Procedure:
 *   print_sequential_prefixes
 * Parameters:
 *   str, a string
 *   ch, a character
 * Purpose:
 *   Print the substrings of str that start with ch.
 * Produces::
 *   [Nothing; called for the side effect]
 * Preconditions:
 *   [No additional]
 * Postconditions:
 *   The output now contains the substrings.
 * Practica:
 *   print_sequential_prefixes ("twas brillig and the slithy toves did gyre", 't');
 *      twas brilling and the slithy toves did gyre
 *      the slighthy toves did gyre
 *      thy toves did gyre
 *      toves did gyre
 */
void print_sequential_prefixes (char *str, char ch);


// +-------------------------+----------------------------------------
// | Basic String Utilities  |
// +-------------------------+

/**
 * Procedure:
 *   string_reverse
 * Parameters:
 *   str, a string
 * Purpose:
 *   Reverse the string in place.
 * Produces:
 *   rev, the reversed string [which is the same as str]
 * Preconditions:
 *   [No additional]
 * Postconditions:
 *   Let len be the length of str and STR be its original value.
 *     rev[i] = STR[len-1-i] for all i from 0 to len-1.
 */
char *string_reverse (char *str);

/**
 * Procedure:
 *   column
 * Parameters:
 *   str, a string
 *   sep, a character
 *   col, an integer
 *   result, a string
 * Purpose:
 *   Grab the col'th column from str, given that columns are separated
 *   by sep.  Copy that column into result.
 * Produces:
 *   ok, an integer
 * Preconditions:
 *   result is big enough to hold the substring.
 *   col >= 0
 * Postconditions:
 *   If str cotains at least col columns, result contains the value in
 *     column col and ok is 1.
 *   Otherwise, result is unmodified and ok is 0.
 * Practica:
 *   column ("alpha:beta:gamma", ':', 0, foo);	// foo now contains "alpha"
 *   column ("alpha:beta:gamma", ':', 1, foo);	// foo contains "beta"
 *   column ("alpha:beta:gamma", ':', 2, foo);	// foo now contains "gamma"
 *   column ("alpha:beta:gamma", ':', 3, foo);	// returns 0
 *   column ("a:b:c", ',', 0, foo);	        // foo now contains "a:b:c"
 *   column ("aardvark,banana", ',', 0, foo);   // foo now contains "aardvark"
 *   column ("aardvark,banana", ',', 1, foo);   // foo now contains "banana"
 */
int column (char *str, char sep, int col, char *result);


// +-------------------------+----------------------------------------
// | String Array Utilities  |
// +-------------------------+

/**
 * Procedure:
 *   string_swap
 * Parameters:
 *   strings, an array of strings
 *   i, an integer
 *   j, an integer
 * Purpose:
 *   Swap the strings in positions i and j.
 * Produces:
 *   [Nothing; called for the side effect]
 * Preconditions:
 *   0 <= i,j < length of strings
 * Postconditions:
 *   If STRINGS has the old value of strings, then
 *     strings[i] = STRINGS[j]
 *     strings[j] = STRINGS[i]
 *     strings[k] = STRINGS[k] for all k != i,j
 */
void string_swap (char *strings[], int i, int j);

/**
 * Procedure:
 *   string_largest
 * Parameters:
 *   strings, an array of strings
 *   limit, an integer
 * Purpose:
 *   Find the largst string in the first limit strings in strings.
 * Produces:
 *   largest, a string
 * Preconditions:
 *   strings has length at least limit
 *   limit >= 1.
 * Postconditions:
 *   strcmp (largest, strings[i]) >= 0 for all 0 <= i < limit
 *   strings is unmodified
 *   There exists a j s.t. largest == strings[j].
 */
char *string_largest (char *strings[], int limit);

/**
 * Procedure:
 *   string_index_of
 * Parameters:
 *   strings, an array of strings
 *   size, an integer
 *   str, a string
 * Purpose:
 *   Find the index of str in the first size elements of strings.
 * Produces:
 *   index, an integer
 * Preconditions:
 *   strings has length at least size.
 * Postconditions:
 *   If exists i s.t., strcmp (strings[i], str) == 0, then index is one such i.
 *   Otherwise, i is -1.
 */
int string_index_of (char *strings[], int size, char *str);

/** 
 * Procedure:
 *   string_sort
 * Parameters:
 *   strings, an array of strings
 *   size, an integer
 * Purpose:
 *   Sort the first size elements of strings.
 * Produces:
 *   [Nothing; Called for the side effect]
 * Preconditions:
 *   size <= length of strings
 * Postconditions:
 *   The final version of strings is a permutation of the original
 *     version of strings.
 *   strcmp (strings[i], strings[i+1]) <= 0 for all i < size-1.
 */
void string_sort (char *strings[], int size);


#endif // _STRING_UTILS_H