Programming Assignment 1 - Hand Counting

Introduction to Computer Science II, Summer 2001

Due Date
Background
The Problem
Testing

Due Date

This assignment is due on Tuesday, 5 June, no later than 2:00 p.m.

See the assignment turn-in page for instructions on turning in your assignment.

Background

A card has the properties suit and rank. A card's suit is one of the four values 'c' (for club), 'd' (for diamond), 'h' (for heart), or 's' (for spade). A card's rank is one of the values 1 through 13; the value 1 is also known as the ace, the value 11 is also known as the jack, the value 12 is also known as the queen, and the value 13 is also known as the king. An individual card is named by its rank and suit; for example "5h" is the five of hearts. The ranks 11, 12, and 13 are usually replaced by the initials J, Q, and K respectively; for example "11D" is the same card as "JD".

A deck of cards is the set of cards forming all possible combinations of suit and rank; a deck of cards contains 13*4 = 52 cards (there are no jokers). A hand is a subset of cards taken from a deck of cards; the size of a hand is the number of cards in the hand.

The Problem

As part of the development team for Solitaire 2001, you have been given the job of implementing a routine to count the number of points in a hand. The prototype for the routine is


int count_hand(int ranks[], char suits[], int hand_size);

count_hand() accepts as input ranks, suits, and hand_size and returns as output the number of points in the hand described by ranks and suits.

The hand contains hand_size cards; hand_size should be between 0 and 52 inclusive. The i-th card in the hand, 1 <= i <= hand_size has rank ranks[i - 1] and suit suits[i - 1]. The return value from count_hand() is the number of points in the hand, or -1 if something's wrong (illegal rank or suit, or bad hand size).

There are three ways for a hand to score points: by runs, pairs, and kinds.

Runs - The largest sequence of three or more cards with consecutive increasing ranks is called a run. For example, the cards 3H, 4D, 5S forms a run of three cards because of the consecutive increasing ranks 3, 4, and 5. Cards in a hand may be re-arranged to form runs.
Because a run is determined by the card and not just the rank, it is possible to form several runs using different cards of the same rank. For example, the hand 9H 10D JD 10C contains two runs: 9H 10D JD and 9H 10C JD.
To be valid, a run must be the largest possible run in the hand. For example, the hand 1C 2C 3D 4S contains one run of four cards; it does not contain a run of three cards.
Each run in an hand contributes points equal to the number of cards in the run. In the first example, the run contributes three points; in the second example, two runs of three cards contributes six points total; in the third example, the run contributes four points.
Pairs - A pair is two cards having the same rank; for example KS and KC is a pair because both cards are kings (that is, have rank 13). As with runs, it is possible to form several pairs with different cards of the same rank; for example the hand 2S 2C 2D contains three pairs (2S 2C, 2S 2D, and 2C 2D). The order of cards in a pair makes no difference; 2S 2C is the same pair as 2C 2S.
Each pair in a hand contributes two points to the hand.
Kinds - A hand is n-of-a-kind if all n cards in the hand have the same suit; for example, 2H 4H 6H KH is a four-of-a-kind hand because all cards in the hand have the heart suit. The hand JD QD KS AD is not a four-of-a-kind hand because one of the cards (KS) has a suit that doesn't match the others; it is also not a three-of-a-kind hand because all cards in the hand are not involved.
An n-of-a-kind hand contributes n points to the hand.

The points in a hand is the sum of points contributed by all runs, pairs, and kinds in the hand.

Testing

You can link the object file test-cnt.o with your implementation of count_hand() to test your implementation. If you're on rockhopper or one of the other linux machines in the PC labs, you can access the object file directly at


/export/home/us/csfac/cs176-summer2001/pa/1/test-cnt.o

You can also download test-cnt.o using a browser by left clicking on the test-cnt.o link while holding down the shift key (this works for Netscape and, I'm assuming, Internet Explorer too). If you forget to hold down the shift key while clicking the left mouse button, you will get a page starting with "ELF" and followed by stuff.

If your implementation is in the source file count-hand.cc, you can link the two using a command such as


$ g++ -o count-hand test-hand.o count-hand.cc

if you've made a local copy of the object file or


$ g++ -o count-hand /export/home/us/cs176-summer2001/pa/1/test-hand.o count-hand.cc

if you're accessing the object file directly. If everything goes well you'll have the executable count-hand, which you can run to test your code.

The object file test-cnt.o will only work on rockhopper or related linux machines; it will not work on Suns and it will not work on Windows systems (you may be able to copy it to your own linux system, assuming you're running a sufficiently up-to-date version of linux).