/***
 *
 * This header file contains three functions that can be used in the card game
 * playing.  The functions are shuffle, deal_two_hands, compare_two_cards, and
 * page_instructions.  The complete user-level specifications for these
 * functions are defined in the program 3 assignment writeup at
 *
 *    http://users.csc.calpoly.edu/~gfisher/classes/101/programs/3/writeup.html
 *
 * There is a companion testing function for each of the three processing
 * functions.  The testing functions, with the aid of some subfunctions, call
 * the processing functions and output the results for inspection.  The testing
 * functions are defined and implemented in cards-test.h and cards-test.c.
 *
 *
 * Author: Gene Fisher (gfisher@calpoly.edu)
 * Created: 23apr12
 * Modified: 26apr12
 *
 */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

/*
 * Constant definitions
 */
#define DECK_SIZE 52           /* Number of cards in a deck */
#define CARD_STR_LEN 4         /* Number of chars in a card string */
#define MAX_HAND_SIZE 20       /* Maximum number of cards in any hand */
#define SUIT_POSITION 2        /* Position of the suit char in a card */
#define BLANK_CARD "   "       /* A blank card in a deck or hand */

/*
 * Type Deck is an array of char strings.  It represents the card deck used in
 * game play.
 */
typedef char Deck[DECK_SIZE][CARD_STR_LEN];
              /*  ^^^^^^^^^  ^^^^^^^^^^^^ */
              /*  ^^^^^^^^^  ^^^^^^^^^^^^ CARD_STR_LEN is the size of each */
              /*  ^^^^^^^^^                 array element (a card string) */
              /*  ^^^^^^^^^  */
              /*  ^^^^^^^^^ DECK_SIZE is the size of the deck array */

/*
 * Type Hand is an array of char strings.  It represents a hand dealt to a game
 * player.  By convention, there is a blank card immediately after the last
 * used element of the hand.
 */
typedef char Hand[MAX_HAND_SIZE + 1][CARD_STR_LEN];

/*
 * Type Card is a 4-element character array.  Except for cards with a face
 * value of 10, character 0 of the card is the face value, and character 1 is
 * the suit.  For 10s, character 2 is the suit.  Note that with this
 * representation, you can distinguish between a 10 and any other card by the
 * lenth of the card string.  That is, cards with a face value of 10 have a
 * strlen of 3, all other cards have a strlen of 2.
 */
typedef char Card[CARD_STR_LEN];


/***
 *
 * Function compare_two_cards returns true if card1 beats card2, by the normal
 * rules of ace-high card ordering.  Specifically,
 *
 *     a. Ace beats king beats queen beats jack beats any numbered card.
 *
 *     b. A numbered card beats another numbered card with a lower value.
 *        E.g., a 10 beats a 3.
 *
 *     c. For two cards of the same face value, the suit of the card determines
 *        order.  Specifically, spades beats hearts beats diamonds beats clubs.
 *
 * The function assumes that card1 and card2 are not equal.
 *
 */
int compare_two_cards(
    Card card1,                 /* 1st card to compare */
    Card card2                  /* 2nd card to compare */
);

/***
 *
 * Function DealTwoHands deals two hands from the given deck.  The input value
 * of the top parameter is the starting position in the deck from which dealing
 * begins.  The num_cards input is how many cards to deal to each hand.  The
 * cards are dealt successively to each hand until either both hands contain
 * num_cards cards, or the deck has run out of cards.  By convention, there is
 * a blank card in the hand immediately after the last card dealt to the hand.
 *
 * The function returns the number cards actually dealt.  If there were enough
 * cards in the deck, the return value is two times the number requested in
 * num_cards.  If there weren't enough cards left in the deck, the return value
 * is how ever many cards were available to deal.
 *
 * Note that the input value of the top paramter defines how many cards are
 * left in the incoming deck.  That is, the number of cards left is DECK_SIZE -
 * top.
 *
 */
int deal_two_hands(
    Deck deck,                  /* Deck to deal from */
    int top,                    /* Index of top card in deck */
    int num_cards,              /* Number of cards to deal to each hand */
    Hand hand1,                 /* 1st hand dealt to */
    Hand hand2                  /* 2nd hand dealt to */
);

/***
 *
 * Function shuffle takes the cards in the given unshuffled_deck and stores
 * them in random positions in the given shuffled_deck.  The degree of
 * randomness is that provided by the UNIX rand function, q.v.  Note that
 * shuffle does not call srand; therefore, the seeding of rand is outside the
 * scope of shuffle.
 *
 */
void shuffle(
    Deck unshuffled_deck,       /* Unshuffled input deck */
    Deck shuffled_deck          /* shuffled output deck */
);

/***
 *
 * Function ComputeFaceValue returns the ace-high integer face value of the
 * given card.  Viz., a numeric face value of 2 through 10 is the number
 * itself.  Jack is 11, queen 12, king 13, and ace 14.
 */
int compute_face_value(
    Card card                   /* Input card */
);

/***
 *
 * Function ComputeSuit returns an integer value reflecting the ordinal value
 * of the suit of the given card.  Viz., spade is 3, heart is 2, diamond is 1,
 * and club is 0.
 *
 */
int compute_suit_value(
    Card card                   /* Input card */
);