Module poker::card

Create and manage poker cards with suits and ranks.

The way poker encodes cards is the key to how poker hands are evaluated. At their core, each card is represented as a single 32-bit integer that encodes all the information we need about it. Using an integer type has many advantages, especially in the context of Rust — the Card type is lightweight, it is Copy, and all operations needed to extract information from the integer are simple enough to execute within a const fn.

Card:
                          bitrank     suit rank   prime
                    +--------+--------+--------+--------+
                    |xxxbbbbb|bbbbbbbb|cdhsrrrr|xxpppppp|
                    +--------+--------+--------+--------+

(Adapted from treys, originally from Cactus Kev)

• b: The first 16 bits, of which 13 are used, represent bit flags that indicate the card’s rank. The rightmost bit being turned on represent a deuce, and the leftmost a king. Only one bit should be turned on at a time for any one card.
• cdhs: Four bitflags that represent the suit of a given card, where c = clubs, d = diamonds, h = hearts, and s = spades.
• r: Four bits of spaces meant for storing a number from 0 to 12, representing the rank of the card, where 0 = deuce, 1 = trey, …, 12 = ace.
• p: Six bits of space meant to hold a prime number that corresponds to the cards rank. A deuce is coded with the first prime number (2), a trey with 3, up until an ace with 41.

This representation may seem redundant, but the different representations are useful during different parts of the evaluation process. Given this, we can be sure of the following example:

use poker::card;

let ace_of_spades = card!(Ace, Spades);
assert_eq!(
    ace_of_spades.unique_integer(),
    // -A-------------|---S|-12-|---42---
    0b0010000_00000000_0001_1100_00101001
);

You will rarely need to work with the unique_integer() directly, but it may be helpful for debugging.

Structs

Card	A single playing card.
ParseToIter	An iterator adaptor returned from Card::parse_to_iter. It doesn’t do anything special, but does have a method try_collect to consolidate Cards into a collection, or fail upon the first error encountered.

Enums

Rank	An enumeration type for representing the thirteen card ranks, from two to ace.
Suit	An enumeration type for representing the four card suits.