Rust Poker #0: Rules, Cards, and Hands

Recently, I’ve been picking up Rust and really enjoying it. I’m finally at the point where building a prototype or reusable utility means I reach for Rust first, even over Python (for convenience) and C++ (for performance). My personal interests recently have been game theory, and specifically applications in various poker games (Texas Holdem, Omaha, etc).

So, let’s combine them! This blog series will be following my development of dealrs (GitHub), a Rust library for dealing cards, ranking hands, and simulating agentic strategies. It is also published as a public crate you can use, here: dealrs (crates.io). So, you can build your own games with it!

If you’re totally unfamiliar with poker and playing cards, I would recommend reading the following resources:

Standard 52-card deck: we’ll be using these as our standard deck of cards
- No jokers! Each card has a suit (Hearts, Spades, Diamonds, or Clubs) and a rank (2-10, Jack, Queen, King, Ace)
- Thus, we have 52 cards in our deck (4 suits * 13 ranks). A bit per card fits well into a u64, which is a mystery tool that will help us later…
List of poker hands: we’ll be considering these as the possible hands we can make

For this first post, we’ll just be focusing on the datatypes and their operations we’ll need. In later posts, we’ll be implementing simulations, automated agents, and more!

Okay. Where do we start?

Well, I figure a good place to start is with the datatypes we’ll be using the most: cards.

Each card is comprised of a rank and a suit. We can represent these with Rust’s enum type. A straightforward definition would look like this:

1
/// All possible ranks (total of 13) of the standard 52-card deck
2
pub enum Rank {
3
    Two,
4
    Three,
5
    Four,
6
    Five,
7
    Six,
8
    Seven,
9
    Eight,
10
    Nine,
11
    Ten,
12
    Jack,
13
    Queen,
14
    King,
15
    Ace,
16
}
17

18
/// All possible suits (total of 4) of the standard 52-card deck
19
pub enum Suit {
20
    Spades,
21
    Hearts,
22
    Clubs,
23
    Diamonds,
24
}
25

26
/// A card is comprised of a rank and a suit, which are the two pieces of information we need to uniquely identify a card
27
pub struct Card(Rank, Suit);

And this would work perfectly well! But, for reasons that will become clear later (like indexing, bitmasking, and lookup tables), it’s preferable to have a “packed” representation of the card that encodes each combination as a unique integer.

While we could use #[repr(u8)], and assign each card a unique integer, it won’t work for Card so well. Instead, we’ll include a Rust macro to help us out, and automagically generate these types while keeping it readable.

1
// a helper that counts the number of items in a sequence of macro arguments
2
macro_rules! count_items {
3
    () => { 0 };
4
    ($head:ident $(, $tail:ident)*) => { 1 + count_items!($($tail),*) };
5
}
6

7
// a macro that defines a 'kind', which is a packed enumeration of items with associated data per each
8
macro_rules! make_kind {
9
    (
10
        $name:ident {
11
            $( $variant:ident => (value = $value:expr, text = $text:expr ) ),* $(,)?
12
        }
13
    ) => {
14
        #[repr(u8)]
15
        #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd)]
16
        pub enum $name {
17
            $( $variant = $value , )*
18
        }
19

20
        impl $name {
21
            pub const NUM: usize = count_items!($( $variant ),*);
22
            pub const ALL: [Self; Self::NUM] = [ $( Self::$variant , )* ];
23

24
            pub const fn from_index(index: u8) -> Self {
25
                Self::ALL[index as usize]
26
            }
27

28
            pub const fn to_index(self) -> u8 {
29
                self as u8
30
            }
31

32
            pub const fn text(self) -> &'static str {
33
                match self {
34
                    $( Self::$variant => $text , )*
35
                }
36
            }
37
        }
38

39
        impl FromStr for $name {
40
            type Err = &'static str;
41
            fn from_str(s: &str) -> Result<Self, Self::Err> {
42
                // attempt to match each variant
43
                for variant in Self::ALL {
44
                    if variant.text() == s {
45
                        return Ok(variant);
46
                    }
47
                }
48
                Err("invalid variant")
49
            }
50
        }
51

52
        impl fmt::Display for $name {
53
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
54
                write!(f, "{}", self.text())
55
            }
56
        }
57
    };
58
}
59

60
make_kind! {
61
    Suit -> SuitData {
62
        Spades   -> ( value =  0, text = "s" ),
63
        Hearts   -> ( value =  1, text = "h" ),
64
        Clubs    -> ( value =  2, text = "c" ),
65
        Diamonds -> ( value =  3, text = "d" ),
66
    }
67
}