freezeout_cards/lib.rs
1// Copyright (C) 2025 Vince Vasta
2// SPDX-License-Identifier: Apache-2.0
3
4//! Freezeout Poker cards types.
5//!
6//! This crate define types to create cards:
7//!
8//! ```
9//! # use freezeout_cards::{Card, Rank, Suit};
10//! let ah = Card::new(Rank::Ace, Suit::Hearts);
11//! let kd = Card::new(Rank::Ace, Suit::Diamonds);
12//! ```
13//!
14//! and a [Deck] type for shuffling, sampling, and iterating cards in the deck.
15//!
16//! For example to iterate through all 7 cards hands:
17//!
18//! ```no_run
19//! # use freezeout_cards::{Card, Deck, Rank, Suit};
20//! let mut counter = 0;
21//! Deck::default().for_each(7, |hand| {
22//! counter += 1;
23//! });
24//! assert_eq!(counter, 133_784_560);
25//! ```
26//!
27//! to sample 10 random 5-cards hands:
28//!
29//! ```
30//! # use freezeout_cards::{Card, Deck, Rank, Suit};
31//! let mut counter = 0;
32//! Deck::default().sample(10, 5, |hand| {
33//! assert_eq!(hand.len(), 5);
34//! counter += 1;
35//! });
36//! assert_eq!(counter, 10);
37//! ```
38//!
39//! The **`parallel`** feature enables parallel sampling and iteration with
40//! a given number of tasks, the following example uses 4 tasks to iterate
41//! all 7 cards hands, the closure `task_id` can be used to store per task data
42//! to reduce contention:
43//!
44//! ```
45//! # #[cfg(feature = "parallel")]
46//! # fn par_for_each() {
47//! # use std::sync::atomic;
48//! # use freezeout_cards::{Card, Deck, Rank, Suit};
49//! let counter = atomic::AtomicU64::new(0);
50//! Deck::default().par_for_each(4, 7, |task_id, hand| {
51//! assert_eq!(hand.len(), 7);
52//! counter.fetch_add(1, atomic::Ordering::Relaxed);
53//! });
54//! assert_eq!(counter.load(atomic::Ordering::Relaxed), 133_784_560);
55//! # }
56//! ```
57//!
58//! for parallel sampling the following uses 4 tasks and sample 10 7-cards hand for
59//! each task:
60//!
61//! ```
62//! # #[cfg(feature = "parallel")]
63//! # fn par_sample() {
64//! # use std::sync::atomic;
65//! # use freezeout_cards::{Card, Deck, Rank, Suit};
66//! let counter = atomic::AtomicU64::new(0);
67//! Deck::default().par_sample(4, 10, 7, |task_id, hand| {
68//! assert_eq!(hand.len(), 7);
69//! counter.fetch_add(1, atomic::Ordering::Relaxed);
70//! });
71//! assert_eq!(counter.load(atomic::Ordering::Relaxed), 40);
72//! # }
73//! ```
74//!
75//! The **`egui`** feature enables the [Textures](egui::Textures) type that gives access
76//! to the card images, see the `board.rs` example for a simple egui app that uses this
77//! crate cards to compute hands probabilities.
78#[warn(clippy::all, rust_2018_idioms, missing_docs)]
79mod deck;
80pub use deck::{Card, Deck, Rank, Suit};
81
82#[cfg(feature = "egui")]
83pub mod egui;