CSE 4208 Lab 1: Players, Hands, and Games

Due by Monday September 29, 2025, at 11:59 pm
Final grade percentage: 10 percent

Objective:

This lab is intended to give you additional hands-on practice with procedural, functional, object-oriented, and generic programming styles, and with additional features of the C++ language and libraries, including:

You will again use procedural, functional, object-oriented, and generic programming paradigms in the C++ language and libraries (as of the C++17 standard) to extend your common and game-specific abstractions for (Partnership Auction) Pinochle and (Texas hold 'em) Poker. To do this, you will first refactor your abstractions for decks of cards from the previous lab assignment, and then add new abstractions for (1) the games themselves, (2) game specific features that re-use your refactored abstractions to hold and manage different sets of cards in the games (e.g., hands in both Pinochle and Hold 'Em Poker, and the board in Hold 'Em Poker), and (3) a factory function that can instantiate the different games polymorphically.

You will also revise the main function of your C++ program from the previous lab assignment so that instead of instantiating objects directly on the stack, it uses the factory function you will write to instantiate a game object of the appropriate type (according to command line parameters passed to it) and then interacts with the game through its virtual member functions.

In subsequent lab assignments you will continue to use and build on these abstractions to implement additional common and game-specific features like examining different combinations of the cards in a set, and evaluating cards and different combinations of cards, according to various scoring functions.

As you develop your code, please use good modularity: for example, if a function's logic has several separable parts (or is long enough to fill the editor's window) you may want to break it up into other smaller functions.

Note: some details of the assignment again are intentionally slightly 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 file.

Assignment:

    Part I - Readings:

  1. The following readings in the required text book may be useful as reference material while working on this lab assignment, and though we'll touch on some of the issues in the next studio sessions, selectively looking up topics and/or reading ahead (on demand as you encounter issues while working on the lab) in the text book (or looking up topics in the on-line C++ Reference) to refresh your familiarity with C++ may be necessary.

  2. Please again review the CSE 4208 Programming Guidelines, and follow them as you develop your solution to each lab assignment this semester.

    Part II - Program Design and Implementation:

  3. Log into one of the Linux Lab machines via qlogin, and (as you did in Studio 0) confirm that the correct version (8.x) of the g++ compiler is installed in your environment there.

  4. In your directory for this course this semester, please create another directory where you will keep your files for your solution to this lab assignment, and cd into it.
  5. In that directory create a readme file (e.g., named readme.txt), in which you will record your observations, design decisions, and other information pertaining to the lab assignment as you develop your solution.
  6. Also copy over the CMakeLists.txt and source (.cpp) and header (.h) files from your previous lab assignment into that directory - you will use (and in some cases modify) them along with additional code you will write, in this lab assignment. If appropriate, you may want to rename some files and update your CMakeLists.txt accordingly (e.g., so that lab0.cpp becomes lab1.cpp as a starting point for this assignment).
  7. First, revise the declaration of the Deck type from the previous lab assignment so that instead of being an abstract base class, it is a class template that is parameterized by rank and suit types, which is derived via public inheritance from a CardSet base class template (whose declarations and definitions you should please put in a separate header and source file respectively) that is also parameterized by rank and suit types.

    Add a protected member variable to the CardSet class template that is a vector of cards parameterized with the rank and suit types that parameterize the Deck class template.

    Change the Deck class template's public print member function so that (1) it is not virtual and (2) has a second parameter of type size_t, and then move it up out of the Deck derived class template into the public section of the CardSet base class template.

    In the template source file for the CardSet type, define its print member function so that it uses the shift operator to insert all the cards in the vector member variable into the ostream that was passed to the print member function, with a whitespace between each card and with a line break after as many cards as are specified by the print member function's second (size_t) parameter have been output in a given line.

    Note that the expression typename vector< Card<R,S> >::iterator lets you declare a variable to use in a for loop to iterate from the position returned by a call to the vector member variable's begin member function up to (but not including) the position returned by a call to the vector member variable's end member function (note that the use of the typename keyword is essential to allow the compiler to figure out what type to use for the iterator variable).

    As you did for the Card struct template in the previous lab assignment, please make sure (1) that at the bottom of the header (.h) file for the Deck class template (within an inclusion guard that begins with #ifdef TEMPLATE_HEADERS_INCLUDE_SOURCE and ends with #endif) it includes the source (.cpp) file for the Deck class template, (2) that the header file for the CardSet class template does so similarly for its corresponding template source file, and (3) that your CMakeLists.txt provides the -DTEMPLATE_HEADERS_INCLUDE_SOURCE flag to g++.

    Also, a reminder that when working with templates, using enough whitespace (and especially putting whitespace between distinct types and the symbols that surround them where necessary) is often essential in order for your code to compile. For example, vector< Foo<T> >::iterator may compile just fine as long as the appropriate header files are included, while vector<Foo<T>>::iterator may not compile because the compiler sees >> as a shift operator.

    Modify the declarations of the PinochleDeck and HoldEmDeck classes so that they are derived through public inheritance from a version of the Deck class template that uses the appropriate concrete rank and suit types as the template's type parameters.

    Remove the vector member variable and the declaration and definition of the print member function from the PinochleDeck and HoldEmDeck classes (since those members are now provided by the Deck base class template).

    At this point you should make sure your program compiles and runs, and gives the same output as your solution to the previous lab assignment did.

  8. Then, extend the declaration and definition of your Deck class template with a shuffle member function that takes no parameters and has a void return type. It should declare local variables for a device callable type (e.g., std::random_device from the <random> library) and a random number generator callable type (e.g., std::mt19937 from the <random> library), using a call to the first one to initialize the second one. It should then call the std::shuffle algorithm (from the <algorithm> library), passing in the results of calls to the vector member variable's begin member function and end member function as the first two arguments and passing in the random number generator variable as the third argument. So that the compiler can figure out the types of the iterators, you may need to explicitly scope the vector member variable, e.g., saying CardSet<R,S>::card_vec.begin() instead of just saying card_vec.begin(), and similarly for the other iterator argument.

    At this point it's a good idea to make sure your code compiles and that when you run the program a few times it produces different orderings for the cards in the decks each time.

  9. As a member of your CardSet class template, declare and define a public right shift operator (operator>>) that takes a (non-const) reference to an object of the same type (i.e., a CardSet parameterized with the same types) and returns a (non-const) reference to an object of the same type. If the object on which the operator is called is empty, the shift operator should throw an exception (e.g., a standard runtime_error). Otherwise, the shift operator should (1) push a card that has the same rank and suit as the card that is at the back of its own vector, onto the back of the vector of the object that was passed to it by reference, (2) pop the card off the back of its own vector, and then (3) return a reference to the object on which it was called (i.e., *this).

    So that code that will use the right shift operator can first test to see if an exception will be thrown, also add a public is_empty member function to the CardSet class template, which takes no parameters and returns a bool value that is false if there are cards in the vector member variable and is true otherwise. Please make sure that you use try and catch blocks appropriately within your code so that any exception that may be thrown is caught at the earliest opportunity to handle it effectively, and no exception is allowed to propagate uncaught out of your program's main function.

  10. In the header and source files for your Deck class template, declare and define a public collect member function that takes a reference to a CardSet that is parameterized with the same rank and suit types as the Deck, and has a void return type. That member function should safely (i.e., without risking throwing an exception, though judicious checking for the passed CardSet being empty) shift all of the cards out of the CardSet and into the Deck.
  11. Add a new C++ header (.h) file to your lab directory, and in it declare an abstract Game base class that has the following member variables and member functions:

    Add a new C++ source (.cpp) file to your lab directory, and in it define a constructor for the Game class that takes an integer (e.g., int argc) and an array of C-style strings (e.g., const char * argv[] or const char * * argv) that contains the names of players, and insert all the players names into the vector of (C++ style) string objects. The argc and argv parameters to the program's main function capture the entire command line with which the program was run, including the name of the executable file and the name of the game that was the next element of the command line. Since this constructor should not insert those first two strings into its member vector, you'll need to adopt a convention for whether (1) this constructor is passed the original argc and argv from the main function and just starts its iteration two positions into the array rather than at position 0, or (2) other code updates the argc and argv arguments so that they only capture the players' names, at some point before this constructor is called.

  12. Add a new C++ header (.h) file and a new C++ source (.cpp) file to your lab directory and in them declare and define (respectively) a PinochleGame class that is derived by public inheritance from the Game abstract base class.

    The PinochleGame class should have

    In its base class / member initialization list, the PinochleGame class constructor should pass its parameters into the constructor for its Game base class, and then (in its body) should push back as many hands into its vector member variable as there are players in the game. To make your code extensible (in future lab assignments) to other Pinochle variations that have different numbers of players, please use the value in the constructor's integer parameter to calculate how many hands to push back, rather than fixing that number for this lab. As noted above, there are different alternatives in how you can handle the fact that the players names appear after the executable program name and the game name in the program's original command line, and the fact that the value of argc that is passed into the program's main function counts the program name and game name as well as the player names.

    The deal member function should repeatedly shift three cards (called a "packet") from the deck to the hand of each player in turn (i.e., the first three cards should be shifted into the first player's hand, the next three cards should be shifted into the next player's hand, etc.) until all cards in the deck have been distributed to the players.

    The play member function should repeatedly: (1) call the deck's shuffle member function; (2) call the deal member function to distribute the cards to the players; (3) print out each player's name and then the cards in their hand to the standard output stream; (4) use the deck's collect member function repeatedly to move the cards back out of each player's hand into the deck; (5) print a string to the standard output stream that asks the user whether or not to end the game; (6) read in a string from the standard input stream - if that string is "yes" the member function should return a value to indicate success, and otherwise it should repeat the sequence of steps.

    Please implement these features (and similarly those of the play member function of the HoldEmGame class) in a modular manner, by breaking them out into separate member functions (e.g., one for printing out player names and hands, one for collecting all the cards back from the players hands into the deck, and one for asking the user whether or not to quit and getting the response). For now, duplicating some of this code between the PinochleGame and HoldEmGame classes is fine, but things like the interaction with the user could be implemented at the level of the Game base class.

  13. Add a new C++ header (.h) file and a new C++ source (.cpp) file to your lab directory and in them declare and define: (1) an enum class HoldEmState enumerated type with monotonically increasing values for the labels preflop, flop, turn, river, and undefined; and (2) a HoldEmGame class that is derived by public inheritance from the Game abstract base class.

    The HoldEmGame class should have

    In its base class / member initialization list, the HoldEmGame class constructor should pass its parameters into the constructor for its Game base class and also initialize the HoldEmState member variable with HoldEmState::preflop. Then (in its body) the constructor should push back as many hands into its vector member variable as there are players in the game. As noted above, there are different alternatives in how you can handle the fact that the players names appear after the executable program name and the game name in the program's original command line, and the fact that the value of argc that is passed into the program's main function counts the program name and game name as well as the player names.

    The deal member function should check the current state of the HoldEmState protected member variable:

    The play member function should repeatedly: (1) call the deck's shuffle member function, (2) set the value of the HoldEmState protected member variable to be HoldEmState::preflop, (3) call the deal member function to deal two cards to each player's hand, (4) print out each player's name and the cards in their hand to the standard output stream, (5) call the deal member function again to deal three cards to the board member variable, (6) print out the string "BOARD (flop):" and then the cards in the board member variable, (7) call the deal member function again to deal the fourth card to the board member variable, (8) print out the string "BOARD (turn):" and then the cards in the board member variable, (9) call the deal member function again to deal the fifth and final card to the board member variable, (10) print out the string "BOARD (river):" and then the cards in the board member variable, (11) use the deck's collect member function repeatedly to move the cards back out of each player's hand into the deck, (12) use the deck's collect member function to move the cards back out of the board into the deck, (13) print a string to the standard output stream that asks the user whether or not to end the game, and (14) read in a string from the standard input stream - if that string is "yes" the member function should return a value to indicate success, and otherwise it should repeat the sequence of steps.

  14. In the source file for your main function, define a create function that takes an integer (e.g., int argc) and an array of C-style strings (e.g., const char *argv[] or const char * * argv) as its parameters and returns a shared pointer parameterized with the Game abstract base class (i.e., shared_ptr<Game>).

    The create function should first declare a local (non-static) variable of type shared_ptr<Game> without initializing it (so that its default initialization makes it point to nothing). The create function should check the game name string (at the appropriate position in the array of C-style strings) and if it is "Pinochle" should assign that variable the result of passsing the integer and array of C-style strings into a call to the make_shared template parameterized with the PinochleGame type (e.g., make_shared<PinochleGame>(argc, argv)); otherwise if the game name string is "HoldEm" the create function should assign the shared pointer variable the result of passsing the integer and array of C-style strings into a call to the make_shared template parameterized with the HoldEmGame type (e.g., make_shared<HoldEmGame>(argc, argv)). Finally, the create function should return the shared pointer variable.

  15. Modify the progam's main function so that its parameters are of the form int argc, const char *argv[] and (instead of declaring stack variables of the Pinochle and Hold 'Em deck types) it first checks that the command line arguments that were passed to the program (after the name of the program executable) consist of either "Pinochle" followed by exactly four player names, or "HoldEm" followed by between two and nine player names, and if not outputs a helpful usage message showing how to call the program and then returns a non-zero error value to indicate a misformed command line. If the command line is well formed, the main function should pass its parameters (argc and argv) into a call to the create function. It should check whether the shared pointer that was returned points to anything (e.g., if(p)) and if so it should return the result of calling the play member function of the Game object that is pointed to by the shared pointer that is returned by the create function. If the shared pointer returned from the create function does not point to anything, the main function should print out an error message and then return a non-zero value corresponding to that problem. Note that when the main function ends, the shared pointer will be destroyed and if it points to anything it will decrement a reference count in its destructor and when the count reaches zero it will deallocate the memory that was dynamically allocated by make_shared, so you don't have to worry about doing that.
  16. In your lab directory, run the cmake -B build && cmake --build build command to compile your code using the CMakeLists.txt, and fix any errors or warnings that occur. Please be sure to note 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 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 file.

  17. Run the executable program repeatedly to test (and confirm) that for any incorrectly formed command line (due to the name of the game or due to the number of players listed following the game's name) the program outputs a helpful error message and returns an appropriate non-zero value to indicate that kind of failure. Then run the executable program repeatedly to confirm that: (1) the correct number of cards is dealt to the correct number of players (and each player's name is correct and appears in the same order as given on the command line) in each turn of play within each run of the program, and the in the Hold 'Em game the common board of cards is dealt correctly; (2) the initial ordering of cards in each game's deck (and thus in the hands to which they are dealt and in the common board of cards in the Hold 'Em game) differs from run to run of the program; and (3) the subsequent ordering of cards in the game's deck (and thus in the hands to which they are dealt) differs from turn to turn of play within each run of the program.
  18. In your readme file, make sure that your names, e-mail addresses, and the lab number (lab 1) 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 file and your CMakeLists.txt, as well as those to your source and header files, before uploading your solution.
  19. Upload to the lab 1 assignment page for CSE 4208 in Canvas a single zip file that contains: (1) your readme file (2) the CMakeLists.txt you used to compile your solution; and (3) all your header and source files for your solution (including any files that you may have copied over unmodified from your previous lab assignment).