Objectives

• Practice using familiar concepts such as arrays, loops, and conditionals in the Java programming language
• Practice with meaningful instance variables
• See an example of how a computer can be used to perform simulations
• See how real-world objects translate into Java classes and how they can work together in a program

Introduction

The Game

1. Shuffle the deck and deal 4 cards, face up and in a single row.
2. Remove cards from those showing. You can remove cards as follows:
   1. If the rightmost 4 cards all have the same suit, remove those 4 to the discard pile. (At the beginning of the game, they'll only be 4 cards showing, but you'll eventually have more.)
   2. If the first card and the fourth card of the rightmost 4 cards have the same suit, remove the two cards in between them (the second and third cards) to the discard pile.
   3. Every time you remove some cards, repeat (a) and (b) (in that order) until you either can't remove any more cards or you have less than four cards showing.
3. Deal a card face up to the right of those already showing. Repeat this if there are less than four face-up cards.
4. Repeat steps 2 and 3 until you have no more cards in the deck. You win if all of the cards have been removed to the discard pile.

The two pictures below demonstrate the two cases under which you can remove cards to the discard pile.

Case (a): Remove rightmost 4 cards (the spades)

Case (b): Remove 2 inner cards from group of last 4 (the heart and the club)

Your Mission

?/1000 games won = ?%
?/2000 games won = ?%
?/3000 games won = ?%
?/4000 games won = ?%
?/5000 games won = ?%
?/6000 games won = ?%
?/7000 games won = ?%
?/8000 games won = ?%
?/9000 games won = ?%
?/10000 games won = ?%

The Details

Card: This class represents a single playing card.

• instance variables: the card's suit and value
• methods:
  • a non-default constructor
  • a toString method that returns the card as a printable string (like "Jack of clubs").
  • appropriate getter methods (setter methods aren't really needed since once a card is created, it won't really change its value or suit.)

Deck: This class represents a collection of Cards.

• instance variables:
  • the collection of Card objects
  • a variable to keep track of which card is next to be dealt. See the deal method below for how to use this variable.
• methods:
  • a constructor
  • a toString method that returns the entire deck as a printable string (concatenate "\n" when you want to include a new line)
  • a deal method that returns the next card dealt. When we deal a card, we won't actually remove it from the deck. Instead, we'll just keep track of an instance variable that marks the place in the deck between already-dealt cards and cards yet to be dealt. So this method updates that variable. This is a common trick in computer science since it's much more time efficient than having to move Card objects around. Make sure you understand this (and see me if you don't)!
  • a shuffle method that randomizes the deck. One way to do this is to pick a random number between 0-51 and swap that index's card with the card at the first (index 0) position in the array. Then pick a number from 1-51 and swap that index's card with the second (index 1) position in the array. Then pick a number from 2-51 and swap that index's card with the card at index 2. Lather, rinse, repeat. How do you pick a random number? Check out the docs for the java.util.Random class. Don't forget the import statement.

SolitaireSimulator: This class handles the simulation.

• instance variables:
  • a Deck of cards
  • an array of cards representing the face-up ones
  • the current number of cards that are facing up
• methods:
  • a constructor
  • a playGame method which is the heart of the simulation. This method should repeatedly deal a card and then try to remove cards according to the rules described above. It should continue this until all cards are dealt. This method should return true if the game was won and false if the game was lost. Try to be modular here by breaking up this method into subtasks (submethods) that you can call on.

Client: This class has the main method. It should call playGame the appropriate number of times and print out statistics to System.out.

You don't have to follow the exact structure I have outlined above (you can have other methods and classes, for example), but you should at least have the four classes listed above.

Remember to practice good programming skills:

• Comment each method and class describing what it does along with any non-obvious preconditions (things you are assuming to be true when the method starts) or postconditions (things you know will be true when the method ends). For example, the playGame method may assume a precondition that the deck of cards has already been shuffled.
• Indicate special cases in your comments. For example, what does the deal method return if there are no more cards to be dealt?
• Use meaningful variable names (and method and class names too)
• Test each method individually
• Use private methods where appropriate

Grading

• 20 points for correct output.
• 10 points for the overall design of your code, including correct instance variables and having straightforward logic.
• 10 points for understandability. This includes things like naming, constants, and documentation.
• 10 points for good modularity.

Administrative statement