Your assignment is to produce a library (For our purposes now, a library is a collection of functions that developers can call instead of having to write them themselves) that provides functions for many common operations of arrays of strings. As an example, one function will find where a string is found in an unordered array of strings. Another will change the order of strings in an array. For each function you must write, this specification will tell you its interface (what it returns, what parameters it takes, and what it must do). You will decide on the implementation (how it will do it).

The source file you turn in will contain all the functions and a main routine. You can have the main routine do whatever you want because we will rename it to something harmless, never call it, and append our own main routine to your file. Our main routine will thoroughly test your functions. You'll probably want your main routine to do the same. If you wish, you may write functions in addition to those required here. We will not directly call any such additional functions. If you wish, your implementation of a function required here may call other functions required here.

The program you turn in must build successfully, and during execution, no function (other than main) may read anything from cin or write anything to cout. If you want to print things out for debugging purposes, write to cerr instead of cout. When we test your program, we will cause everything written to cerr to be discarded instead — we will never see that output, so you may leave those debugging output statements in your program if you wish.

All of the functions you must write take at least two parameters: an array of strings, and the number of items the function will consider in the array, starting from the beginning. For example, in

     string people[8] = {

           "samwell", "jon", "margaery", "daenerys",

           "tyrion", "sansa", "jaime", "cersei"

     };

     int i = locate(people, 5, "cersei");  // should return -1 (not found)

even though the array has 8 elements, only the first 5 had values we were interested in for this call to the function; the function must not examine the others.

Notwithstanding each function's behavior described below, all functions that return an int must return −1 if they are passed any bad arguments (e.g. a negative array size, or a position that would require looking at the contents of an element past the last element we're interested in). Unless otherwise noted, passing 0 to the function as the array size is not itself an error; it merely indicates the function should examine no elements of the array.

The one error your function implementations don't have to handle, because they can't, is when the caller of the function lies and says the array is bigger than it really is. For example, in this situation, the function locate can't possibly know that the caller is lying about the number of interesting items in the array:

     string folks[5] = { "samwell", "jon", "margaery", "daenerys", "tyrion" };

     int i = locate(folks, 25, "cersei");  // Bad call of function, but

           // your locate implementation doesn't have to check for

           // this, because it can't.

To make your life easier, whenever this specification talks about strings being equal or about one string being less than or greater than another, the case of letters matters. This means that you can simply use comparison operators like == or < to compare strings. Because of the character collating sequence, all upper case letters come before all lower case letters, so don't be surprised. The FAQ</a has a note about string comparisons.

Here are the functions you must implement:

int enumerate(const string a[], int n, string target); The number of strings in the array are returned that are equal to target. [Of course, in this and other functions, if n is negative, the paragraph above that starts "Notwithstanding" trumps this by requiring that the function return −1. Also, in the description of this function and the others, when we say "the array", we mean the n elements that the function is aware of.] As noted above, case matters: Do not consider "jon" to be equal to "JoN".