Ferrous-Solitaire/solitaire_core/src/card.rs

use serde::{Deserialize, Serialize};

/// Card suit.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum Suit {
    Clubs,
    Diamonds,
    Hearts,
    Spades,
}

impl Suit {
    /// All four suits in declaration order.
    pub const SUITS: [Self; 4] = [Self::Clubs, Self::Diamonds, Self::Hearts, Self::Spades];

    /// Returns `true` for red suits (Diamonds, Hearts).
    pub fn is_red(self) -> bool {
        matches!(self, Suit::Diamonds | Suit::Hearts)
    }

    /// Returns `true` for black suits (Clubs, Spades).
    pub fn is_black(self) -> bool {
        !self.is_red()
    }
}

/// Card rank, Ace through King.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum Rank {
    Ace = 1,
    Two = 2,
    Three = 3,
    Four = 4,
    Five = 5,
    Six = 6,
    Seven = 7,
    Eight = 8,
    Nine = 9,
    Ten = 10,
    Jack = 11,
    Queen = 12,
    King = 13,
}

impl Rank {
    /// All thirteen ranks in ascending order.
    pub const RANKS: [Self; 13] = [
        Self::Ace,
        Self::Two,
        Self::Three,
        Self::Four,
        Self::Five,
        Self::Six,
        Self::Seven,
        Self::Eight,
        Self::Nine,
        Self::Ten,
        Self::Jack,
        Self::Queen,
        Self::King,
    ];

    /// Numeric value: Ace = 1, King = 13.
    pub fn value(self) -> u8 {
        self as u8
    }

    const fn new(n: u8) -> Option<Self> {
        match n {
            1 => Some(Self::Ace),
            2 => Some(Self::Two),
            3 => Some(Self::Three),
            4 => Some(Self::Four),
            5 => Some(Self::Five),
            6 => Some(Self::Six),
            7 => Some(Self::Seven),
            8 => Some(Self::Eight),
            9 => Some(Self::Nine),
            10 => Some(Self::Ten),
            11 => Some(Self::Jack),
            12 => Some(Self::Queen),
            13 => Some(Self::King),
            _ => None,
        }
    }

    /// Returns the rank `n` steps above `self`, or `None` if it would exceed King.
    pub const fn checked_add(self, n: u8) -> Option<Self> {
        Self::new((self as u8).saturating_add(n))
    }

    /// Returns the rank `n` steps below `self`, or `None` if it would go below Ace.
    pub const fn checked_sub(self, n: u8) -> Option<Self> {
        match (self as u8).checked_sub(n) {
            Some(v) => Self::new(v),
            None => None,
        }
    }
}

/// A single playing card.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Card {
    /// Unique identifier for this card within the deal. Stable across moves and undo.
    pub id: u32,
    /// The card's suit (Clubs, Diamonds, Hearts, Spades).
    pub suit: Suit,
    /// The card's rank (Ace through King).
    pub rank: Rank,
    /// Whether the card is visible to the player. Face-down cards may not be moved.
    pub face_up: bool,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn rank_values_are_sequential() {
        for (i, r) in Rank::RANKS.iter().enumerate() {
            assert_eq!(r.value(), (i + 1) as u8);
        }
    }

    #[test]
    fn rank_as_u8_matches_value() {
        for r in Rank::RANKS {
            assert_eq!(r as u8, r.value());
        }
    }

    #[test]
    fn rank_checked_add_boundary() {
        assert_eq!(Rank::King.checked_add(1), None);
        assert_eq!(Rank::Queen.checked_add(1), Some(Rank::King));
        assert_eq!(Rank::Ace.checked_add(1), Some(Rank::Two));
        assert_eq!(Rank::Five.checked_add(3), Some(Rank::Eight));
    }

    #[test]
    fn rank_checked_sub_boundary() {
        assert_eq!(Rank::Ace.checked_sub(1), None);
        assert_eq!(Rank::Two.checked_sub(1), Some(Rank::Ace));
        assert_eq!(Rank::King.checked_sub(1), Some(Rank::Queen));
        assert_eq!(Rank::Five.checked_sub(3), Some(Rank::Two));
    }

    #[test]
    fn suit_suits_contains_all_four() {
        assert_eq!(Suit::SUITS.len(), 4);
        assert!(Suit::SUITS.contains(&Suit::Clubs));
        assert!(Suit::SUITS.contains(&Suit::Diamonds));
        assert!(Suit::SUITS.contains(&Suit::Hearts));
        assert!(Suit::SUITS.contains(&Suit::Spades));
    }

    #[test]
    fn suit_red_and_black_are_complementary() {
        for suit in [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades] {
            assert_ne!(
                suit.is_red(),
                suit.is_black(),
                "{suit:?} must be exactly one of red/black"
            );
        }
        assert!(Suit::Diamonds.is_red() && Suit::Hearts.is_red());
        assert!(Suit::Clubs.is_black() && Suit::Spades.is_black());
    }
}