Assignment 16

Assignment 16: Part 2 (`Deck`)

Task

Now that you have a PlayingCard, you can model a deck of playing cards.

Steps

Create a class named Deck. It should contain the following public methods. Again, the (reusable) documentation explains what each should do.

/**
 * Constructs a new deck of 52 standard playing cards with no jokers.
 * If the parameter shuffled == true, the new deck will be shuffled.
 * Otherwise, it will be in sorted order.
 */
public Deck(boolean shuffled)

/**
 * Constructs a deck of 52 shuffled playing cards.
 */
public Deck()

/**
 * Removes the top card from this deck and returns it.
 * If this deck is empty, will return null instead.
 */
public PlayingCard draw()

/**
 * Returns the number of cards currently remaining in this deck.
 */
public int getSize()

/**
 * Shuffles the cards remaining in this deck.  That is, only
 * reorders those cards that have not yet been drawn.  The deck's
 * current size does not change and any previously drawn cards 
 * are NOT returned to the deck.
 */
public void shuffle()

Make sure your method signatures match these exactly. Any instance variables you have should be private. All you really need is a PlayingCard[] and int count variable. (Or, if you'd rather use an ArrayList instead, one ArrayList<PlayingCard>.)

When constructing a Deck, you need to add cards to it in some sort of order so that you know you generated and added one of each of the 52 cards. The particular order is up to you--all the Aces, then all the 2s, etc; or all of one suit and then all of the next suit.

The first Deck constructor allows the user of your code to ask for a deck either with or without shuffling. Most of the time, they'll probably want it shuffled though, so the second constructor makes the deck a little easier to use. [Hint: Writing the second constructor is very simple if you remember how to call one constructor from another.]

For the draw() method, we don't want the Deck to crash if some programmer accidentally tries to draw a card from an empty deck. There's not much we can do in this situation though--either document what exception the method will throw in this situation, or else return null. For this implementation, I chose the latter approach.

For the shuffle() method, check out the Fisher-Yates algorithm for a relatively easy, but efficient and effective shuffling method. (It's easiest to make sense of the algorithm by looking at the pen and pencil examples. You may use any code you find here, but only if you cite where you got it! Be warned that you'll probably need to modify the code a bit, since you won't always be shuffling a full deck.)

You may write additional methods if you desire--such as a toString() method--but only those listed above are required.

Sample Output

Depends on how much you want to test your Deck at this point.

What to Submit

Hang onto this file for now--you're not going to submit it until after you finish A16-Part 3.

Grading

See A16-Part 3.

FAQs

So, although we can create Joker playing cards, there aren't actually going to be any in the Deck?

That is correct. Mostly, the Joker was a nice clean way to handle invalid arguments to the PlayingCard constructor (since we haven't learned how to throw exceptions yet, only catch them). It is true that, for certain games, someone might actually want Jokers included in a new deck. So we could provide a third constructor: Deck(boolean shuffled, int jokers), which would allow someone to specify exactly how many jokers they want added (since sometimes you only want one, not two). But this extra code is not really necessary at this point.

Why are there two constructors? What is the difference between them? How do you use the constructor that takes a boolean parameter?

The idea here is that sometimes you may want the cards in a new Deck to be ordered, though most of the time you'll probably want them shuffled. The first constructor lets you specify this when you create the deck:

  Deck ordered = new Deck(false); //ordered deck
  Deck random = new Deck(true); //shuffled deck

However, most of the time, you'll proably end up giving true as the argument. Therefore, the second constructor should do the same thing as Deck(true) and provide a shuffled deck:

  Deck mixedUp = new Deck(); //shuffled deck

This makes the Deck easier/faster to use most of the time.

To implement this, write the Deck(boolean) constructor first. Load the cards into the array in some sort of order using a couple for loops. Then, after the loops, you can:

  if (shuffled) {
    this.shuffle();
  }

See how this will call the shuffle() method is shuffled == true and will skip the call if shuffled == false? Also, this way your shuffling code occurs only in one place: in your shuffle method!

You can then write the body of Deck() in one line by invoking the other constructor with the value of true. As I mentioned in lab, you do this with the line:

this(true);

How do I load the array with cards?

Well, first you need to declare the PlayingCard[] as an instance variable. Then construct an array of size 52. You can either do this when you declare the variable or at the start of the constructor (as shown here):

  private PlayingCard[] cards;
  ...

  public Deck(boolean shuffled) {
    this.cards = new PlayingCard[52];
    ...
  }

Then you need to load the cards array with 52 new PlayingCard objects. Each element of the array will hold a (reference to) a PlayingCard. (And remember that each PlayingCard object then has its own suit and value stored inside it, along with associated methods. Pretty neat, huh?) So, use one or two loops to generate all 52 combinations of suit and value, and, in the inner loop:

  cards[count] = new PlayingCard(value, suit);
  count++;

You need a count instance variable to tell you how many cards are left in your array as you draw them out later. So you can use that here to also load the array. It can start at 0; after the cards are all loaded, it will be 52.

As always, there are other ways to do this, but this technique is short and sweet, especially if you're stuck.

How do I know if my Deck was constructed correctly?

Probably the easiest way is to temporarily print out the contents of the array that contains all the Deck's cards at the end of the constructor. This will verify that the constructor did its job. To do this, you'll either need to use a for loop or else figure out how java.util.Arrays.toString(Object[]) works.

If you chose to use an ArrayList instance variable (instead of an array) and named it cards, then you can simply add this line as the last line of the Deck constructor:

  System.out.println(this.cards);

As with printing any object, this println statement actually invokes the ArrayList's toString() method, which in turn will invoke your PlayingCard's toString() method to print each card in the list.

Remember this printing is just for debugging purposes to see if your constructor worked. Once you're done testing, remove it!

Shuffling tips

If you are implementing the Fisher-Yates algorithm given above, note that you will have to change the code given in a number of ways:

First of all, the code given is for a static method that sorts a full array of ints:
```
    public static void shuffle(int[] array)
```
Your shuffle method must instead be an instance method that takes no parameters:
```
    public void shuffle()
```
(Note that you may overload the shuffle method--that is, define more than one shuffle method with different parameter lists--if you want to. So you could have a version of the shuffle method that takes an array. However, this is unnecessary and you are still required to have the version that takes no parameters.)
You don't need to pass any parameters to the shuffle method because you already have an instance variable (an array) that contains all the cards. Basically, instead of shuffling array, you'll be shuffling cards.
You're shuffling PlayingCards, not ints.
Remember that you may not always be shuffling a full deck! So don't shuffle up to cards.length, but only up to the number of cards currently in the deck.

If you chose to use an ArrayList<PlayingCard> instead of a PlayingCard[] arrray, then:

You'll have to rewrite the algorithm to use ArrayList methods instead of array subscripts. For example, this line:
```
    int tmp = array[k];
```
gets the element (an int) from index k in the array and stores it into a temp variable. You would need to change this to something like:
```
    PlayingCard temp = this.cards.get(k);
```
Similarly, the line:
```
    array[n] = tmp;
```
(which changes the value of the element at index n to tmp) would become:
```
    cards.set(n, temp);
```
Alternately, there is a shuffle method in the API that might be handy. See java.util.Collections. (You'll have to understand inheritance and interfaces to truly understand how you can pass an ArrayList to this method, however.)

According to that Wikipedia page, Java is probably only going to be able to provide a subset of all possible deck permutations. Is this okay?

Yeah, that's fine. If you're really worried, I suppose you could have your shuffle method actually shuffle the deck multiple times, but it's not required.

How do I test my Deck?

One way to test it is with a few temporary print statements as you're writing the code, as described in the FAQ above regarding the constructor.

For more comprehensive testing, though, it is hard to test your deck when you can't see its current state. Therefore, I'd recommend you write a method that prints all the undrawn cards currently remaining in the array/ArrayList. This method should not change the state of those cards though. This could either be a print() or toString() method. For example:

  public String toString() {
    String cardsLeft = "";
    for (int i = this.count - 1; i >= 0; i--) {
      cardsLeft += this.cards[i].toString() + "\n";
    }
    return cardsLeft;
  }

Then write a main method that does the following:

Construct an ordered deck and print it. Are the cards ordered? Are all 52 cards there?
Draw some cards and print them out. Is draw() working correctly? Do you get the next card in the deck each time?
Print the deck again. Were the drawn cards properly removed from the deck?
Shuffle the deck and print it out. Did a partial deck shuffle properly? Make sure none of the cards you drew out earlier now appear back in the shuffled deck!
Draw some more cards and print them. Drawing works fine from a shuffled deck?
Create a new shuffled deck and print it out. Is it properly shuffled?

On to A16, Part 3 →