dealrs: a Rust library for card games

dealrs is a Rust library for playing card games (like poker), providing a set of low-level utilities for efficiently working with cards, decks, evaluation, ranking, and combinatorial exploration thereof. On top of this, it provides a few higher level frameworks for evaluating simulations, strategies, game variants, optimal play, and building your own applications.

This is currently a work-in-progress, and the API is not yet stable.

• List of poker hands
• Poker Project (CodeThrowdown)
  • 5 Card Single Deck Hands

Usage

See the examples for usage.

As a quick sanity check, you can run the examples/sim/pairs.rs example to see if the library is working correctly:

$ cargo run --package dealrs --example sim-pairs
Simulation complete, final results:
Ran a total of 10000 deals, finding 589 pairs
On a random deal, this is a 5.89% chance of happening
On average, you will find a pair every 16.98 deals

Unless something is completely broken with your system (never this library 😉), you should expect around a 1/17 chance of finding a pair in a random deal.

Benchmarks

There are lots of benchmarks, since performance is important for card games. You can run all of them with the following command:

$ cargo bench
# ...

This will take a very long time and produce a report. Performance is pretty good, but the benchmarking is not exhaustive or particularly organized. In the future, I hope to have exhaustive benchmarks that can be used to objectively inform decisions about algorithmic improvements.

Development

Regenerating Lookup Tables

If you need to regenerate the lookup tables, you can do so with the following command:

# regenerates the lookup tables for the best 5-card hands
# NOTE: --no-default-features is required if the files do not exist, since by default they are included and will cause a compilation error
$ cargo run --package dealrs --bin lutrank --no-default-features --

You can double check the generated report (lutrank.md) to see if the tables are correct, and when debugging.

Publishing Releases

To publish a new release, update the version in Cargo.toml, commit the changes, and then run the following command:

$ cargo publish --dry-run

If this succeeds, then you can actually publish the release with the following command:

$ cargo publish

This will upload the new version to crates.io.