playin_cards/

lib.rs

#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![doc = include_str!("../README.md")]
//! # Usage
//! The main interface is the [`Card`] which represents a single playing card
//! which may be one of the cards in a standard 52-card deck of playing cards,
//! or a Joker which may be either black or red. A [`Card`] instance can be
//! easily be parsed from a 2-`char` `str` with one of `A23456789TJQK` as the
//! first char and one of `SsCcDdHh♥♣♠♦` as the second char.
//!
//! `Card` can also be formatted as a 2-`char` unicode string such `A♣`, `5♥`,
//! `J♠` with the [`Display`] trait or as a sinlg-`char` unicode card char such
//! as `🃑`, `🂵`, `🂫` with the [`UpperHex`] trait.

#[allow(unused_imports)]
use std::fmt::{Display, UpperHex};
#[cfg(feature = "rank-partialord")]
use std::cmp::{PartialOrd, Ordering};

use itertools::Itertools;
use strum_macros::EnumIter;
use strum::IntoEnumIterator;

/// number of cards in a standard 52-card deck of French-suited playing cards
pub const CARDS_PER_DECK: u8 = 52;

/// A French-suited playing card
///
/// The card is represented by either `Joker`, which has only a `Color` or a
/// `Regular` which represents a normal card from a standard 52-card deck,
/// comprised of a [`Rank`] and a [`Suit`]
///
/// ## Parsing
///
/// `Card` can easily be parsed from a 2-`char` `str` representation where the
/// first char represents the [`Rank`] as one of `A23456789TJQK`) and the
/// second char represents the [`Suit`] as one of `SsCcDdHh♠♥♣♦`
/// ```
/// use playin_cards::{Card::*, Rank::*, Suit::*};
///
/// // Parse a Card instance from a 2-char ASCII string:
/// assert_eq!("AS".parse(), Ok(Regular{rank: Ace, suit: Spades}));
/// assert_eq!("3D".parse(), Ok(Regular{rank: Three, suit: Diamonds}));
/// assert_eq!("JC".parse(), Ok(Regular{rank: Jack, suit: Clubs}));
/// assert_eq!("9H".parse(), Ok(Regular{rank: Nine, suit: Hearts}));
///
/// // A Card can also be parsed from Unicode representation:
/// assert_eq!("A♣".parse(), Ok(Regular{rank: Ace, suit: Clubs}));
/// assert_eq!("5♠".parse(), Ok(Regular{rank: Five, suit: Spades}));
/// assert_eq!("8♥".parse(), Ok(Regular{rank: Eight, suit: Hearts}));
/// ```
///
/// ## Formatting
/// `Card` can be formatted as a 2-`char` Unicode `str` using [`Display`] or as
/// a single-`char` unicode `str` using [`UpperHex`]
///
/// ```
/// use playin_cards::{Card::*, Rank::*, Suit::*};
///
/// // `Display` uses ASCII for rank and Unicode for Suit:
/// assert_eq!(format!("{}", Regular{rank: Ace, suit: Clubs}),     "A♣");
/// assert_eq!(format!("{}", Regular{rank: King, suit: Diamonds}), "K♦");
/// assert_eq!(format!("{}", Regular{rank: Ace, suit: Clubs}),     "A♣");
///
/// // `UpperHex` uses Unicode card chars
/// assert_eq!(format!("{:X}", Regular{rank: Ace, suit: Clubs}), "🃑");
/// ```
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub enum Card {
    /// Regular playing card from a standard 52-card deck.
    Regular { rank: Rank, suit: Suit },
    /// A Joker
    Joker(Color),
}

/// Ranks of a standard French-suited playing card
///
/// ## Values
/// `Rank` instances do not have a notion of "value". Value is not an intrinsic
/// property of the rank of a playing card, rather it is a property imposed on
/// it by the rank valuing system of the specific game in which the card is
/// being used; for example one game might assign a value of 11 to `Ace` while
/// another may assign it a value of 1, and others may allow the player to
/// decide if it is 1 or 11 based on other cards in their hand. For this reason
/// it is inappropriate for this library to expose a public interface to the
/// concept of value for `Rank`, it is up to this library's consumers to define
/// how values are assigned to ranks, if at all.
///
/// That said, the discriminants of the variants of `Rank` start at 1 for Ace
/// and increase by 1 all the way up to `King`, as this facilitates the
/// implementations of what is by-far the most common rank valuing system used
/// in card games.
/// ```
/// use playin_cards::Rank;
/// assert_eq!(Rank::Ace as u8, 1);
/// assert_eq!(Rank::Six as u8, 6);
/// assert_eq!(Rank::King as u8, 13);
/// ```
///
/// ## Conversions
///
/// `Rank` is bidirectionally convertible with `char` via `From` and `TryFrom`:
///
/// ```
/// use playin_cards::{Rank, ParseError};
///
/// // get the char corresponding to a `Rank` instance
/// assert_eq!(char::from(Rank::King), 'K');
/// assert_eq!(char::from(Rank::Five), '5');
/// assert_eq!(char::from(Rank::Jack), 'J');
///
/// // parse a single `char` to a `Rank`
/// assert_eq!(Rank::try_from('Q'), Ok(Rank::Queen));
/// assert_eq!(Rank::try_from('4'), Ok(Rank::Four));
/// assert_eq!(Rank::try_from('T'), Ok(Rank::Ten));
/// assert_eq!(Rank::try_from('A'), Ok(Rank::Ace));
///
/// // Parsing fails if an invalid char is used
/// assert_eq!(Rank::try_from('Y'), Err(ParseError::InvalidChar));
/// ```
///
/// ## Iteration
/// Thanks to [`strum`], the vairants of [`Rank`] can be iterated over:
/// ```
/// use playin_cards::Rank;
/// use strum::IntoEnumIterator;
///
/// let mut rankiter = Rank::iter();
/// assert_eq!(rankiter.next(), Some(Rank::Ace));
/// assert_eq!(rankiter.next(), Some(Rank::Two));
/// assert_eq!(rankiter.next(), Some(Rank::Three));
/// assert_eq!(rankiter.next(), Some(Rank::Four));
/// // You get the point...
///
/// ```
#[derive(EnumIter, Debug, PartialEq, Clone, Copy, Eq, Hash)]
pub enum Rank {
    Ace = 1,
    Two,
    Three,
    Four,
    Five,
    Six,
    Seven,
    Eight,
    Nine,
    Ten,
    Jack,
    Queen,
    King,
}

#[cfg(feature = "rank-partialord")]
impl PartialOrd for Rank {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        PartialOrd::partial_cmp(self as u8, other as u8)
    }
}

/// Suits of a standard French-suited playing card
///
/// ## Conversions
/// `Suit` is bidirectionally convertible with `char`:
/// ```
/// use playin_cards::Suit;
/// // Converting Suit -> char uses Unicode
/// assert_eq!(char::from(Suit::Spades),   '♠');
/// assert_eq!(char::from(Suit::Hearts),   '♥');
/// assert_eq!(char::from(Suit::Diamonds), '♦');
/// assert_eq!(char::from(Suit::Clubs),    '♣');
/// // Converting char -> Suit allows uppercase ASCII, lowercase ASCII, or
/// // Unicode
/// assert_eq!(Suit::try_from('S'), Ok(Suit::Spades)); // Uppercase
/// assert_eq!(Suit::try_from('s'), Ok(Suit::Spades)); // Lowercase
/// assert_eq!(Suit::try_from('♠'), Ok(Suit::Spades)); // Unicode
/// ```
/// ## Iteration
/// Thanks to [`strum`], the variants of [`Suit`] can be iterated over:
/// ```
/// use playin_cards::Suit;
/// use strum::IntoEnumIterator;
///
/// let mut suititer = Suit::iter();
/// assert_eq!(suititer.next(), Some(Suit::Hearts));
/// assert_eq!(suititer.next(), Some(Suit::Diamonds));
/// assert_eq!(suititer.next(), Some(Suit::Spades));
/// assert_eq!(suititer.next(), Some(Suit::Clubs));
///
/// ```
#[derive(EnumIter, Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Suit {
    Hearts,
    Diamonds,
    Spades,
    Clubs,
}

/// Color of a [`Suit`] or [`Card`]. Either Red or Black
#[derive(Debug, PartialEq, Clone, Copy, Eq, Hash)]
pub enum Color {
    Red,
    Black,
}

mod format;
mod parse;

pub use parse::ParseError;

impl Suit {
    /// Set of allowed chars which can be converted to [`Suit`] with
    /// [`TryFrom<char>`]
    pub const ALLOWED_CHARS: &'static str = "SsCcHhDd♠♣♥♦";

    /// Return the color of the `Suit`
    pub fn color(self) -> Color {
        match self {
            Suit::Hearts | Suit::Diamonds => Color::Red,
            Suit::Spades | Suit::Clubs => Color::Black,
        }
    }
}

impl Card {
    /// Return the color of the `Card` which is just the color of its `Suit`
    pub fn color(self) -> Color {
        match self {
            Self::Regular { rank: _, suit } => suit.color(),
            Self::Joker(color) => color,
        }
    }

    /// Return `true` if this card is a Joker, otherwise return `false`
    pub fn is_joker(self) -> bool {
        match self {
            Self::Regular { rank: _, suit: _ } => false,
            Self::Joker(_) => true,
        }
    }
}

impl Rank {
    /// Set of allowed chars which can be converted to [`Rank`] with
    /// [`TryFrom<char>`]
    pub const ALLOWED_CHARS: &'static str = "A23456789TJQK";
}

impl From<(Rank, Suit)> for Card {
    fn from((rank, suit): (Rank, Suit)) -> Self {
        Self::Regular{rank, suit}
    }
}

/// Generate an (unshuffled) [shoe](https://en.wikipedia.org/wiki/Shoe_(cards))
///
/// Return an unshuffled shoe containing `n_decks` decks. If `with_jokers`
/// `true`, Each deck has 54 cards, all the cards in a standard 52-card deck,
/// and 2 Jokers, one Black and one Red. If `with_jokers` is `false`, each deck
/// only contains the 52 cards in a standard deck.
pub fn gen_shoe(n_decks: u8, with_jokers: bool) -> Vec<Card> {

    let extra_cards: u8 = if with_jokers {2} else {0};
    // total number of cards in the shoe
    let total_cards = n_decks as usize * (CARDS_PER_DECK + extra_cards) as usize;

    // preallocate memory for the shoe
    let mut output = Vec::with_capacity(total_cards);
    for _ in 0..n_decks  {
        let deck_iter = Rank::iter()
            .cartesian_product(Suit::iter())
            .map(Card::from);
        output.extend(deck_iter);
        if with_jokers {
            output.extend([Card::Joker(Color::Red), Card::Joker(Color::Black)]);
        }
    }
    output
}

#[cfg(test)]
mod test {
    use super::*;
    use strum::IntoEnumIterator;
    use itertools::Itertools;
    use std::collections::HashMap;

    pub const FULL_DECK_CARDS: [Card; 52] = [
        Card::Regular{suit: Suit::Hearts, rank: Rank::Ace},
        Card::Regular{suit: Suit::Hearts, rank: Rank::Two},
        Card::Regular{suit: Suit::Hearts, rank: Rank::Three},
        Card::Regular{suit: Suit::Hearts, rank: Rank::Four},
        Card::Regular{suit: Suit::Hearts, rank: Rank::Five},
        Card::Regular{suit: Suit::Hearts, rank: Rank::Six},
        Card::Regular{suit: Suit::Hearts, rank: Rank::Seven},
        Card::Regular{suit: Suit::Hearts, rank: Rank::Eight},
        Card::Regular{suit: Suit::Hearts, rank: Rank::Nine},
        Card::Regular{suit: Suit::Hearts, rank: Rank::Ten},
        Card::Regular{suit: Suit::Hearts, rank: Rank::Jack},
        Card::Regular{suit: Suit::Hearts, rank: Rank::Queen},
        Card::Regular{suit: Suit::Hearts, rank: Rank::King},
        Card::Regular{suit: Suit::Diamonds, rank: Rank::Ace},
        Card::Regular{suit: Suit::Diamonds, rank: Rank::Two},
        Card::Regular{suit: Suit::Diamonds, rank: Rank::Three},
        Card::Regular{suit: Suit::Diamonds, rank: Rank::Four},
        Card::Regular{suit: Suit::Diamonds, rank: Rank::Five},
        Card::Regular{suit: Suit::Diamonds, rank: Rank::Six},
        Card::Regular{suit: Suit::Diamonds, rank: Rank::Seven},
        Card::Regular{suit: Suit::Diamonds, rank: Rank::Eight},
        Card::Regular{suit: Suit::Diamonds, rank: Rank::Nine},
        Card::Regular{suit: Suit::Diamonds, rank: Rank::Ten},
        Card::Regular{suit: Suit::Diamonds, rank: Rank::Jack},
        Card::Regular{suit: Suit::Diamonds, rank: Rank::Queen},
        Card::Regular{suit: Suit::Diamonds, rank: Rank::King},
        Card::Regular{suit: Suit::Spades, rank: Rank::Ace},
        Card::Regular{suit: Suit::Spades, rank: Rank::Two},
        Card::Regular{suit: Suit::Spades, rank: Rank::Three},
        Card::Regular{suit: Suit::Spades, rank: Rank::Four},
        Card::Regular{suit: Suit::Spades, rank: Rank::Five},
        Card::Regular{suit: Suit::Spades, rank: Rank::Six},
        Card::Regular{suit: Suit::Spades, rank: Rank::Seven},
        Card::Regular{suit: Suit::Spades, rank: Rank::Eight},
        Card::Regular{suit: Suit::Spades, rank: Rank::Nine},
        Card::Regular{suit: Suit::Spades, rank: Rank::Ten},
        Card::Regular{suit: Suit::Spades, rank: Rank::Jack},
        Card::Regular{suit: Suit::Spades, rank: Rank::Queen},
        Card::Regular{suit: Suit::Spades, rank: Rank::King},
        Card::Regular{suit: Suit::Clubs, rank: Rank::Ace},
        Card::Regular{suit: Suit::Clubs, rank: Rank::Two},
        Card::Regular{suit: Suit::Clubs, rank: Rank::Three},
        Card::Regular{suit: Suit::Clubs, rank: Rank::Four},
        Card::Regular{suit: Suit::Clubs, rank: Rank::Five},
        Card::Regular{suit: Suit::Clubs, rank: Rank::Six},
        Card::Regular{suit: Suit::Clubs, rank: Rank::Seven},
        Card::Regular{suit: Suit::Clubs, rank: Rank::Eight},
        Card::Regular{suit: Suit::Clubs, rank: Rank::Nine},
        Card::Regular{suit: Suit::Clubs, rank: Rank::Ten},
        Card::Regular{suit: Suit::Clubs, rank: Rank::Jack},
        Card::Regular{suit: Suit::Clubs, rank: Rank::Queen},
        Card::Regular{suit: Suit::Clubs, rank: Rank::King},
    ];

    #[test]
    /// Tests that all Ranks cast to their respective values of u8
    fn rank_cast_u8() {
        assert_eq!(Rank::Ace as u8, 1, "Ace as u8 was not 1");
        assert_eq!(Rank::Two as u8, 2, "Two as u8 was not 2");
        assert_eq!(Rank::Three as u8, 3, "Three as u8 was not 3");
        assert_eq!(Rank::Four as u8, 4, "Four as u8 was not 4");
        assert_eq!(Rank::Five as u8, 5, "Five as u8 was not 5");
        assert_eq!(Rank::Six as u8, 6, "Six as u8 was not 6");
        assert_eq!(Rank::Seven as u8, 7, "Seven as u8 was not 7");
        assert_eq!(Rank::Eight as u8, 8, "Eight as u8 was not 8");
        assert_eq!(Rank::Nine as u8, 9, "Nine as u8 was not 9");
        assert_eq!(Rank::Ten as u8, 10, "Ten as u8 was not 10");
        assert_eq!(Rank::Jack as u8, 11, "Jack as u8 was not 11");
        assert_eq!(Rank::Queen as u8, 12, "Queen as u8 was not 12");
        assert_eq!(Rank::King as u8, 13, "King as u8 was not 13");
    }
    #[test]
    fn suit_colors() {
        assert_eq!(Suit::Spades.color(), Color::Black);
        assert_eq!(Suit::Hearts.color(), Color::Red);
        assert_eq!(Suit::Clubs.color(), Color::Black);
        assert_eq!(Suit::Diamonds.color(), Color::Red);
    }
    #[test]
    fn card_colors() {
        for card in FULL_DECK_CARDS[..26].iter() {
            assert_eq!(card.color(), Color::Red, "{} incorrectly identified as Red", card);
        }
        for card in FULL_DECK_CARDS[26..].iter() {
            assert_eq!(card.color(), Color::Black, "{} incorrectly identified as Black", card);
        }
        assert_eq!(Card::Joker(Color::Black).color(), Color::Black);
        assert_eq!(Card::Joker(Color::Red).color(), Color::Red);
    }
    #[test]
    fn is_joker() {
        for card in FULL_DECK_CARDS.iter() {
            assert!(!card.is_joker(), "{} incorrectly identified as joker", card)
        }
        assert!(Card::Joker(Color::Black).is_joker());
        assert!(Card::Joker(Color::Red).is_joker());
    }
    fn count(shoe: &[Card]) -> HashMap<Card, u16> {
        let mut map = HashMap::new();
        for &card in shoe {
            *map.entry(card).or_insert(0) += 1;
        }
        map
    }
    fn test_shoe(n: u8, w_jokers: bool) {
        let shoe = gen_shoe(n, w_jokers);
        let n_jokers = if w_jokers {2 * n} else {0} as usize;
        assert_eq!(shoe.len(), CARDS_PER_DECK as usize * n as usize + n_jokers);
        let map = count(&shoe);
        for (rank, suit) in Rank::iter().cartesian_product(Suit::iter()) {
            assert_eq!(map.get(&Card::Regular{rank, suit}), Some(&(n as u16)));
        }
        if w_jokers {
            assert_eq!(map.get(&Card::Joker(Color::Black)), Some(&(n as u16)));
            assert_eq!(map.get(&Card::Joker(Color::Red)), Some(&(n as u16)));
        }
    }
    /// Assert that there is exactly 1 of each card in the results of `gen_shoe`.
    #[test]
    fn gen_shoe_no_jokers_single() {
        test_shoe(1, false);
    }
    /// Assert that there is exactly N of each card in the results of `gen_shoe`.
    #[test]
    fn gen_shoe_no_jokers_multi() {
        test_shoe(6, false);
    }
    #[test]
    fn gen_shoe_w_jokers() {
        test_shoe(1, true);
    }
    #[test]
    fn gen_shoe_w_jokers_multi() {
        test_shoe(4, true);
    }
}