poker 0.3.0

A crate for speedy poker hand evaluation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

# `poker`: The Poker Evaluation Crate

[![Crates.io](https://img.shields.io/crates/v/poker)](https://crates.io/crates/poker)
[![Docs.rs](https://docs.rs/poker/badge.svg)](https://docs.rs/poker)
[![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)

`poker` is a Rust crate for the speedy evaluation of poker hands. It it based on
the [`treys`](https://github.com/ihendley/treys)
Python package and the algorithms found within, with mild adaptations and some
personal touches to try to make it as idiomatic as possible in Rust.

```rust
use poker::{Evaluator, cards, Card};

fn main() {
    // Create a hand evaluator
    let eval = Evaluator::new();

    // Generate a shuffled deck
    let mut deck = Card::generate_shuffled_deck().to_vec();

    // Deal a hand
    let hand: Vec<Card> = deck.drain(..5).collect();

    // Evaluate
    let result = eval.evaluate(hand).expect("Couldn't evaluate hand!");

    // Print the hand result
    println!("{}", result);
}
```

## Using `poker`

Add poker to the `dependencies` in your `Cargo.toml` file:

```toml
[dependencies]
poker = "0.3"
```

## Features

`poker` currently has two features. One depends on the [`rand`](https://crates.io/crates/rand) crate,
in order to shuffle generated decks. This is enabled by default.

The second feature, which is also not enabled by default is `static_lookup`. Enabling
this feature opens up the `poker::evaluate::static_lookup` module, which contains
the free `evauluate` function. It works similar to `Evaluator::evaluate`, but
semantically it uses a static data structure that does not rely on heap allocations.

There is no real benefit to using the feature yet, but it is an experimental first step
for possible `no_std` support in the future. To enable this feature:

```toml
[dependencies]
# To use without `rand`, add `default-features = false`
poker = { version = "0.3", features = ["static_lookup"] }
```

## A Note on Performance

For readability, the `#[inline]` attribute has been removed from function
declarations. In order to ensure `rustc` can make appropriate inlining and
optimization decisions, remember to use link-time optimization in your release
builds. This comes at the cost of slower compilation times. In your
`Cargo.toml`:

```toml
[profile.release]
# ...
lto = true # the default is false!
```

## Examples

`poker` includes two fun builtin examples: `poker-repl` and `jacks-or-better`.
`poker-repl` is a `repl`-like environment when you can evaluate different poker
hands. `jacks-or-better` is a terminal re-creation of the Jacks or Better
video poker game. Payouts based on [this image](https://www.gamblingsites.com/wp-content/uploads/2016/08/video-poker-pay-table-jacks-or-better.png).
Rules for the game can be found [here](https://www.onlinepoker.net/games/jacks-or-better).

> ### DISCLAIMER
>
> The `jacks-or-better` example from the `poker` crate has themes of gambling
> using a currency called `credits`. This program is meant for example purposes
> only to illustrate one possible use of this library. There is no risk associated
> with running the example as it can be terminated and restarted at any time.
>
> Please be aware of the possible financial risk of real gambling.

You can install these examples through `cargo` by running the following command:

```bash
cargo install poker --example=poker-repl
cargo install poker --example=jacks-or-better
# Then you can run the programs, assuming they were installed somewhere in $PATH
poker-repl
jacks-or-better
```

You can also run the examples through a cloned git repository.

```bash
git clone https://github.com/deus-x-mackina/poker.git
cd poker
cargo run --example=poker-repl
cargo run --example=jacks-or-better
```

## License

Licensed under the MIT license ([LICENSE.txt](LICENSE.txt) or <http://opensource.org/licenses/MIT>).