Examples

In this example we use a scenario from the game Texas Hold’em:

Community cards: 9c 4c 4s 9d 4h (both players share these cards)

  • Player 1: Qc 6c

  • Player 2: 2c 9h

Both players have full houses. Player 1 only has fours full over nines, while player 2 has nines full over fours, which is stronger than player 1.

All the code and compiling instructions can be found in the examples directory.

Example code in C++

We can construct a Card by providing a two-character string:

phevaluator::Card a = phevaluator::Card("Qc");

The method EvaluateCards takes 5 to 7 Card parameters and returns a Rank. You can also provide the strings directly and let the Card values be constructed implicitly, to make your code cleaner:

phevaluator::Rank rank1 =
  phevaluator::EvaluateCards("9c", "4c", "4s", "9d", "4h", "Qc", "6c");

phevaluator::Rank rank2 =
  phevaluator::EvaluateCards("9c", "4c", "4s", "9d", "4h", "2c", "9h");

A stronger hand compares as less than a weaker hand:

assert(rank1 > rank2); // rank2 is stronger

We can get the rank value among all 7462 possible hands. This ranking is identical to the return value of Cactus Kev’s evaluator: the best rank has value 1 (a Royal Straight Flush), while the worst rank is 7462.

int value1 = rank1.value(); // 292
int value2 = rank2.value(); // 236

We can tell the ranking category of the rank, either using the method category (which returns an enumerator) or describeCategory (which returns a string). In this example both players hold full houses:

assert(rank1.category() == FULL_HOUSE);
assert(rank1.describeCategory() == "Full House");

assert(rank2.category() == FULL_HOUSE);
assert(rank2.describeCategory() == "Full House");

We can get more detail from the rank using describeRank or describeSampleHand. The best 5-card hand from player 2 is 9-9-9-4-4:

assert(rank2.describeSampleHand() == "99944");

Suit information is missing from that method because it usually doesn’t matter, unless all five cards share the same suit. The isFlush method tells us whether the sample hand is a flush. In this example it is not:

assert(!rank2.isFlush());

Finally, describeRank gives a short description of the sample hand:

assert(rank2.describeRank() == "Nines Full over Fours");

Example code in C

In the C version the evaluation is trickier, since we have to convert each card to an integer ourselves. The formula is rank * 4 + suit. See Card Id for the full mapping.

// Community cards
int a = 7 * 4 + 0; // 9c
int b = 2 * 4 + 0; // 4c
int c = 2 * 4 + 3; // 4s
int d = 7 * 4 + 1; // 9d
int e = 2 * 4 + 2; // 4h

// Player 1
int f = 10 * 4 + 0; // Qc
int g = 4 * 4 + 0; // 6c

// Player 2
int h = 0 * 4 + 0; // 2c
int i = 7 * 4 + 2; // 9h

After constructing all the cards, use evaluate_7cards to get a rank value. The best rank is 1 (a Royal Straight Flush) and the worst is 7462:

int rank1 = evaluate_7cards(a, b, c, d, e, f, g); // 292
int rank2 = evaluate_7cards(a, b, c, d, e, h, i); // 236

When comparing two rank values, the smaller one is stronger:

assert(rank1 > rank2); // rank2 is stronger

Similar to the C++ interface, we can get the rank category:

enum rank_category category = get_rank_category(rank1);
assert(category == FULL_HOUSE);

const char *categoryDesc = describe_rank_category(category); // "Full House"

Or get the sample hand from the rank:

describe_sample_hand(rank2); // 9 9 9 4 4

Although suit information is missing here, we only care about whether all five cards are the same suit. Check it using is_flush:

is_flush(rank2); // false

Finally, describe_rank gives a short description of the rank:

describe_rank(rank2); // Nines Full over Fours