A fast and idiomatic Rust implementation of a Texas Hold'em poker hand evaluator. This library showcases Rust's powerful pattern matching capabilities by evaluating 5-card poker hands using native match control flow with array and struct patterns.
- Pattern-Driven Evaluation: Uses Rust's
matchexpressions with array and struct patterns for clean, readable hand evaluation - Comprehensive Hand Rankings: Supports all standard poker hands from High Card to Royal Flush
- Convenient Macros: Ergonomic macros (
hand!,newcard!,assert_rank!) for working with cards and hands - CLI Tool Included: Interactive command-line interface for testing and demonstrations
- Well-Tested: 28+ unit tests covering edge cases and hand ranking scenarios
- Zero-Cost Abstractions: Fast evaluation using Rust's compile-time optimizations
See the MatchHandEvaluator implementation for details on the pattern-matching approach.
Add poker-face to your Cargo.toml:
[dependencies]
poker-face = "0.2.0"Or use cargo:
cargo add poker-faceThe library provides convenient macros for working with poker hands:
use pokerface::{hand, newcard, assert_rank, Rank, Card, Suit};
fn main() {
// Create and evaluate hands using the hand! macro
let royal = hand!["Ad","Kd","Qd","Jd","10d"];
assert_eq!(Rank::evaluate(&royal), Rank::RoyalFlush);
// Create individual cards
let ace_hearts = newcard!["Ah"];
assert_eq!(ace_hearts, Card::new(14, Suit::Hearts));
// Test hand rankings
assert_rank!(hand!["Kd", "Kh", "Kc", "Ks", "Qd"], Rank::FourOfAKind);
assert_rank!(hand!["2d", "2h", "Qc", "Qs", "Qd"], Rank::FullHouse);
}The package includes an interactive command-line tool for demonstrations:
# Run directly with cargo
cargo run -q
# Or build and install
cargo build --release
cargo install --path .
pokerfaceExample output:
Poker Face - 🦀 for ♠️ ♣️ ♥️ ♦️
1. Let's shuffle a deck...
2. Let's take 2 hands of 5 cards each from the deck
Player 1 has: J♥️ 10♥️ 9♠️ 7♠️ 5♥️
Player 2 has: K♥️ K♣️ K♦️ Q♦️ 6♥️
3. Let's evaluate the hands...
Player 1 has a [HighCard with a highcard of value J♥️]
Player 2 has a [ThreeOfAKind]
4. Celebrate the winner:
The winner is Player 2!
The evaluator recognizes all standard Texas Hold'em poker hands:
- Royal Flush: A♠ K♠ Q♠ J♠ 10♠
- Straight Flush: 9♥ 8♥ 7♥ 6♥ 5♥
- Four of a Kind: K♦ K♣ K♥ K♠ Q♦
- Full House: Q♠ Q♥ Q♦ 3♣ 3♦
- Flush: A♣ J♣ 8♣ 4♣ 3♣
- Straight: 10♦ 9♠ 8♥ 7♣ 6♦
- Three of a Kind: 7♥ 7♦ 7♠ K♣ 2♠
- Two Pair: J♠ J♦ 4♥ 4♣ 9♠
- One Pair: 10♥ 10♣ A♠ 5♦ 3♥
- High Card: A♦ K♣ 8♥ 5♠ 2♦
Poker-Face uses Rust's pattern matching to evaluate hands in a readable and efficient way. Instead of using lookup tables or bitwise operations, it leverages Rust's structural pattern matching on arrays and structs. This approach makes the code:
- Readable: Each hand type is clearly expressed as a pattern
- Maintainable: Easy to understand and modify
- Type-Safe: Compile-time guarantees prevent errors
- Performant: Zero-cost abstractions mean no runtime overhead
Check out the MatchHandEvaluator source to see pattern matching in action.
Full API documentation is available on docs.rs.
Key types and functions:
Card: Represents a playing card with rank and suitRank: Enum representing all poker hand rankingshand!: Macro for creating hands from string notationnewcard!: Macro for creating individual cardsassert_rank!: Test macro for validating hand rankings
Contributions are welcome! If you have suggestions for new features or find any issues, please:
- Check existing issues first
- Open a new issue to discuss your idea or bug report
- Submit a pull request with your changes
All feedback is appreciated!
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Built with Rust 🦀 for poker enthusiasts