CSE 332 Lab 3: Dictionaries, Tile Collections, and Permutations

Lab dates: Wednesday September 30, Wednesday October 7, and Wednesday October 14, 2009
Due by Tuesday October 20 at 11:59 pm (deadline for e-mailing a zip file with your solution)
Final grade percentage: 10 percent

Objective:

In this lab and in the subsequent labs, you are encouraged to re-use and modify code from your previous lab solutions - if you choose do this, please put a completely new copy of any header and source files from your previous lab(s) in the new lab project directory you create. This can avoid some potential for error or confusion within Visual Studio, and also ensures you have a backup copy that you could go back to if a modification you try doesn't pan out.

In the next lab assignment you will use these features to allow a user to play a text-based solitaire version of the game "scrabble", with a board on which interlocking words are played.

Assignment:

Part I - Readings:

1. The following readings in the optional text books and reference web pages may be useful as reference material while working on this lab assignment, and though we'll touch on most of the issues in the next few studio selectively looking up topics and/or reading ahead (on demand as you encounter issues while working on the lab) is also encouraged:
   • C++ classes: Prata pp. 355-358, 445-499, 515-517; Deitel 6th Edition pp. 81-117, 487-557; Deitel 7th Edition pp. 68-102, 395-423, 430-453
   • STL find algorithm: Prata pp. 1103-1104; Deitel 6th Ed. pp. 1071, 1112-1114; Deitel 7th Ed. pp. 929, 970-971; http://www.cppreference.com/wiki/stl/algorithm/find

   • STL http://www.cppreference.com/wiki/stl/algorithm/random_shuffle algorithm: Prata pp. 885-889, 1109, 1114; Deitel 6th Ed. pp. 1071, 1109, 1111; Deitel 7th Ed. pp. 929, 967, 969; http://www.cppreference.com/wiki/stl/algorithm/random_shuffle

   • STL next_permutation algorithm: Prata pp. 933-934, 1116, 1125-1126; Deitel 6th Ed. pp. 1129; Deitel 7th Ed. pp. 986; http://www.cppreference.com/wiki/stl/algorithm/next_permutation

2. The constructor, destructor, operator, accessor, and mutator method examples in the C++ classes lecture slides give an overview of class syntax and structure you may need for this lab.

3. The STL algorithm examples in the C++ C++ functions, classes, and templates lecture slides also may be helpful when implementing parts this lab.

4. Please read the following CSE 332 Programming Guidelines which relevant to the previous labs and please follow them as you implement your solution: A.1-A.6, A.9-A.11, A.17, B.7, B.9, B.13, B.15, B.16, B.20-B.23, B.25, B.30, B.33, B.34, C.1-C.4 and C.6-C.9.

   Please also review and follow the additional guidelines that may be relevant to this lab: A.7-A.8 (exceptions), A.12-A.15 (pointers and arrays), A.16 (debugging), B.1-B.6 (dynamic memory allocation), B.10-B.12 (constructors), B.18 (copy constructor and assignment operator), B.22 first part (inclusion guards), and C.5 (pointer arithmetic).

   Part II - Program Design and Implementation:

   Note: the details of this assignment are again intentionally somewhat under-specified, leaving you some room to choose what you think is the best way to implement them, as long as what you do is reasonable and you explain your design decisions in comments in the code and in your Readme.txt file.

5. Open up Visual Studio, and create a new Win32 Console Application Visual C++ project for lab 3.
6. Declare and define a class to represent a Dictionary) with a private member variable that is an STL-supplied container of C++ style strings (e.g., of type vector<string> or list<string>). The public interface for this class should be:

   • A default constructor in which the container member variable is initialized to be empty;

   • A destructor that if necessary releases dynamically allocated memory and performs other cleanup tasks (if the compiler-supplied destructor is sufficient then you may use it rather than declaring/defining your own, but if you do please put a comment in the class declaration explaining why that is ok to do.

   • A constructor that takes a file name and passes it into a call to the add method (see next). Make sure that if the add method fails the object remains in a valid (though perhaps uninitialized) state.

   • An "add" method that takes a file name, opens up the file, reads in strings from the file (as we did in labs 1 and 2) and inserts them into the container member variable. Feel free to reuse or modify code from your previous labs in your implementation of this method. As in the previous labs, if a file cannot be opened the program should output an appropriate error message and return a non-zero value to indicate failure.

   • A const "size" method that returns the number of elements in the container member variable.

   • A const "print" method that takes a reference to an ostream (that is defaulted to being a reference to cout if no parameter is provided when the method is called) and prints out each string in the dictionary on a separate line using the passed ostream.

   • A const "find" method that takes a reference to a const C++ style string and returns a bool value indicating whether (true) or not (false) the passed string was found in the dictionary (hint: the STL find algorithm can help you implement this, though you are also free to implement your own approach such as keeping the strings sorted in the container member variable and then doing iterative or binary search over the strings depending on the type of container you chose to use).

7. Declare and define a class (e.g., of type LetterTileCollection) to represent a collection of letter tiles. This class should have a private member variable that is an STL-supplied container of letter tiles (e.g., of type vector<LetterTile> or list<LetterTile>). The public interface for this class should be:

   • A default constructor in which the container member variable is initialized to be empty;

   • A copy constructor that takes a const reference to another letter tile collection object and initializes itself to contain the same sequence of letter tiles as in the passed object;

   • A constructor that takes a file name and passes it into a call to the add method (see below). Make sure that if the add method fails the object remains in a valid (though perhaps uninitialized) state.

   • An assignment operator that takes a const reference to another letter tile collection object, checks for self-assignment, and otherwise clears out any existing letter tiles and updates itself to contain the same sequence of letter tiles as in the passed object;

   • A destructor that if necessary releases dynamically allocated memory and performs other cleanup tasks (if the compiler-supplied destructor is sufficient then you may use it rather than declaring/defining your own, but if you do please put a comment in the class declaration explaining why that is ok to do.

   • A const "size" method that returns the number of elements in the container member variable.

   • An "add" method that takes a file name, opens up the file, reads in letter tile definitions from the file (as we did in lab 1) and inserts them into the container member variable. Feel free to reuse or modify code from your previous labs in your implementation of this method. As in the previous labs, if a file cannot be opened the program should output an appropriate error message and return a non-zero value to indicate failure.

   • A "move" method that takes a reference to another (non-const) object of the same type and an unsigned integer, removes either as many letter tiles as are given by the second parameter or as many as there are in the passed object (whichever is least) from the passed object, and adds those letter tiles to the object on which the move method was called.

   • A const "print" method that takes a reference to an ostream (that is defaulted to cout if no parameter is provided when the method is called) and prints out each tile in the collection (its letter and score as we did in labs 1 and 2) on a separate line using the passed ostream.

   • A const equivalence operator that takes a reference to a const object of the same type and returns true if and only if exactly the same sequence of letter tiles appears in both objects.

   • A const less than operator that takes a reference to a const object of the same type and returns true if and only if the the sum of the scores of the tiles in the object on which the operator was called is less than the sum of the scores of the tiles in the passed object.

   • A "shuffle" method that randomly rearranges the sequence of letter tiles in the container member (hint: the STL random_shuffle algorithm can help you implement this).

   • A "permute" method that rearranges the sequence of letter tiles in the container member variable into its next lexicographically greater permutation (hint: the STL next_permutation algorithm can help you implement this).

   • A const "as string" method that returns (by value) a C++ style string containing the sequence of letters represented by the sequence of tiles in the container member variable.

   • A const "score" method that returns (by value) the sum of the scores of the tiles in the container member variable.

8. Declare and define a class (e.g., of type WordCollection) to represent the possible valid rearrangements of a collection of letter tiles that make up words that are found in a dictionary. This class should have a private member variable that is an STL-supplied container of letter tile collections (e.g., of type vector<LetterTileCollection> or list<LetterTileCollection>). The public interface for this class should be:

   • A constructor that takes a const reference to a letter tile collection object and a const reference to a dictionary object, produces all permutations of the collection object (hint: use a local non-const object to do this), checks whether each permutation is a word in the dictionary, and stores each of them that is in the dictionary in its container member variable.

   • A destructor that if necessary releases dynamically allocated memory and performs other cleanup tasks (if the compiler-supplied destructor is sufficient then you may use it rather than declaring/defining your own, but if you do please put a comment in the class declaration explaining why that is ok to do).

   • A const print method that takes a reference to an ostream (that is defaulted to cout if no parameter is provided when the method is called) and prints out the score and string of each of the tile collection objects it contains, with each object on a separate line using the passed ostream.

   Word collection objects should print out the permutations they contain in order by ascending score. How you implement this is up to you, but establishing the ordering in the constructor as an invariant is one nice way to do this.

   Please decide whether or not you want to implement (by declaring and defining a copy constructor and assignment operator for the class) or prevent (see programming guideline B.18) copying of Dictionary and WordCollection objects. In your ReadMe.txt file, please state and justify your decisions about this and please also describe how you tested whether or not your approach to this worked for both of those types.

9. In your project's main function:

   • Modify the signature of your main function so that it matches the one shown in the second example given in the C++ program structure and development environment lecture slides (the one that uses the variable names argc and argv).

   • Make sure your main program checks the command line arguments and requires (but accepts in either order) a "-D" or "-d" followed by the name of a dictionary file and a "-T" or "-t" followed by the name of a tile definitions file.

   • Before proceeding, your program should check whether or not it can open the dictionary file for reading (using an ifstream) and if not it should generate an error message and return a non-zero failure code. Otherwise it should try to open the tile definition file for reading (using an ifstream). If it cannot open the tile definition file for reading it should try to open it for writing (using an ofstream) and output tile definitions into it based on counting and scoring the letters in the dictionary file as you did in the previous lab.

     Hint: If successful make sure to close the files before proceeding, since otherwise the program may fail.

   • Use the name of the dictionary file to initialize a local Dictionary object in your main function.

   • Use the name of the tile definitions file to initialize a local LetterTileCollection object in your main function. This object will serve as a pool of tiles from which other collections can be drawn.

   • Default construct three more LetterTileCollection objects in your main function. Then, for each of these objects (1) shuffle the pool object described above and move seven tiles from the pool into the object you just default constructed.

   • With each of the LetterTileCollection objects into which you moved tiles (also passing in the Dictionary object), construct a WordCollection object.

   • Call the print method of each of the objects above so that it prints out its contents to cout.

   • Upon completion, if no other errors have occurred, the program should return 0 to indicate success.
10. Build your project, and fix any errors or warnings that occur. Please be sure to note all of the different kinds of errors or warnings you ran into (though you don't have to list every instance of each kind) in your ReadMe.txt file. If you were fortunate enough not to run into any errors or warnings, please note that instead, where you would have listed errors or warnings in your ReadMe.txt file.

11. Open up a Windows console (terminal) window and change to the directory where your program's executable file was created by Visual Studio (see the first studio exercises document for more details on this, if you don't remember them).

12. Run the executable program through a series of trials that test it with good coverage of cases involving both well formed and badly formed inputs. For this lab one especially useful test is to check whether the output printed by your program consistently represents the contents of valid dictionary and tile definition files it was given. In your ReadMe.txt file please document which cases you ran (i.e., what the command lines were) and summarize what your program did and whether that is correct behavior, in each case.

13. In your ReadMe.txt file, make sure that your name and the lab number (lab 3) are at the top of the file, and that you've documented whether you ran into any errors or warnings while developing your solution (and if so what they were) and what the executable program did for each of the trials you ran. Be sure to save your changes to your ReadMe.txt file, as well as those to your source (and header) file(s) before preparing your solution zip file.

14. Prepare a zip file that contains your project's source, header, and ReadMe.txt files (except for stdafx.h, stdafx.cpp or other Windows-generated files you did not modify), by:
    • Creating a new lab3 folder on your Windows desktop;
    • Copying the appropriate files (here, ReadMe.txt, and the source and header files where you wrote your code) from Visual Studio into that folder; and then
    • Right-clicking on the folder and selecting the Send To->Compressed (zipped) Folder item in the menu that appears.

    Send the zip file containing your lab 3 solution as an e-mail attachment to the course e-mail account (cse332@cec.wustl.edu) by the submission deadline for this assignment. If you need to make changes to your lab solution you are welcome to send a new zip file, and we will grade the latest one received prior to the deadline (according to the time stamp the server puts on the e-mail).

    Part III - Code structure and style: (optional, worth up to 5% extra credit)

    The goal of this optional part of the assignment is to have you take a deeper look at the programming guidelines, and to think about and describe their intent and relevance in your program. While an additional level of documentation is required for this extra credit portion, all labs will be evaluated for conformance to the specific CSE 332 Programming Guidelines noted at the top of this assignment. Please ask for help from your professor or teaching assistants if you are uncertain about how to do this extra credit part or if you run into any difficulty with it.

15. In your readme file, please add a section clearly marked "extra credit" and in it explain for each of the following sets of CSE 332 Programming Guidelines (1) which ones do or do not apply to your lab solution (and why or why not), and for those that do apply (2) explain how you followed (or how and why you deviated from) them:

    • A.7-A.8 (exceptions)

    • A.12-A.15 (pointers and arrays)

    • A.16 (debugging)

    • B.1-B.6 (dynamic memory allocation)

    • B.10-B.12 (constructors)

    • B.18 (copy constructor and assignment operator)

    • B.22 first part (inclusion guards)

    • C.5 (pointer arithmetic)