feat: Improve InvalidShoupaiError (#56)

* feat: Merge bingpai-related errors from `InvalidShoupaiError` into the `InvalidBingpai` variant

* test: Add unit tests

* feat: Merge FuluMianzi-related errors from `InvalidShoupaiError` into the `InvalidFuluMianzi` variant

* refactor: Reorder variants of `InvalidShoupaiError`

* refactor: Validate if hand is empty only in case of short hand

Author: Apricot-S

src/bingpai.rs

@@ -50,19 +50,23 @@ use thiserror::Error;
 /// ```
 pub type Bingpai = [u8; NUM_TILE_INDEX];
 
+/// Errors that occur when an invalid pure hand (純手牌) is provided.
 #[derive(Debug, Error)]
-pub(crate) enum InvalidBingpaiError {
+pub enum InvalidBingpaiError {
+    /// Same tile count exceeds 4.
     #[error("same tile count must be 4 or less but was {0}")]
     ExceedsMaxNumSameTile(u8),
+    /// Total tile count exceeds 14.
     #[error("total tile count must be 14 or less but was {0}")]
     ExceedsMaxNumBingpai(u8),
-    #[error("hand is empty")]
+    /// Pure hand is empty.
+    #[error("pure hand is empty")]
     EmptyBingpai,
+    /// Total tile count is not a multiple of 3 plus 1 or 2.
     #[error("total tile count must be a multiple of 3 plus 1 or 2 but was {0}")]
     InvalidNumBingpai(u8),
-    #[error(
-        "tile index {0} (must be outside 1 (2m) to 7 (8m)) cannot be used in 3-player mahjong"
-    )]
+    /// Contains tiles that cannot be used in 3-player mahjong (2m to 8m).
+    #[error("tile index {0} cannot be used in 3-player mahjong")]
     InvalidTileFor3Player(usize),
 }
 
@@ -83,10 +87,10 @@ impl BingpaiExt for Bingpai {
         if num_bingpai > MAX_NUM_SHOUPAI {
             return Err(InvalidBingpaiError::ExceedsMaxNumBingpai(num_bingpai));
         }
-        if num_bingpai == 0 {
-            return Err(InvalidBingpaiError::EmptyBingpai);
-        }
         if num_bingpai % 3 == 0 {
+            if num_bingpai == 0 {
+                return Err(InvalidBingpaiError::EmptyBingpai);
+            }
             return Err(InvalidBingpaiError::InvalidNumBingpai(num_bingpai));
         }
 

src/calculate.rs

@@ -203,6 +203,7 @@ pub fn calculate_replacement_number_3_player(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::bingpai::InvalidBingpaiError;
 
     #[test]
     fn calculate_replacement_number_standard_tenpai() {
@@ -251,7 +252,52 @@ mod tests {
         let replacement_number = calculate_replacement_number(&bingpai, &None);
         assert!(matches!(
             replacement_number.unwrap_err(),
-            InvalidShoupaiError::EmptyShoupai
+            InvalidShoupaiError::InvalidBingpai(InvalidBingpaiError::EmptyBingpai)
+        ));
+    }
+
+    #[test]
+    fn calculate_replacement_number_too_many_tiles() {
+        let bingpai: Bingpai = [
+            1, 1, 1, 1, 0, 0, 0, 0, 0, // m
+            1, 1, 1, 1, 0, 0, 0, 0, 0, // p
+            1, 1, 1, 1, 0, 0, 0, 0, 0, // s
+            1, 1, 1, 0, 0, 0, 0, // z
+        ];
+        let replacement_number = calculate_replacement_number(&bingpai, &None);
+        assert!(matches!(
+            replacement_number.unwrap_err(),
+            InvalidShoupaiError::InvalidBingpai(InvalidBingpaiError::ExceedsMaxNumBingpai(15))
+        ));
+    }
+
+    #[test]
+    fn calculate_replacement_number_5th_tile() {
+        let bingpai: Bingpai = [
+            5, 0, 0, 0, 0, 0, 0, 0, 0, // m
+            1, 1, 1, 1, 0, 0, 0, 0, 0, // p
+            1, 1, 1, 1, 0, 0, 0, 0, 0, // s
+            1, 0, 0, 0, 0, 0, 0, // z
+        ];
+        let replacement_number = calculate_replacement_number(&bingpai, &None);
+        assert!(matches!(
+            replacement_number.unwrap_err(),
+            InvalidShoupaiError::InvalidBingpai(InvalidBingpaiError::ExceedsMaxNumSameTile(5))
+        ));
+    }
+
+    #[test]
+    fn calculate_replacement_number_incomplete_hand() {
+        let bingpai: Bingpai = [
+            4, 4, 4, 0, 0, 0, 0, 0, 0, // m
+            0, 0, 0, 0, 0, 0, 0, 0, 0, // p
+            0, 0, 0, 0, 0, 0, 0, 0, 0, // s
+            0, 0, 0, 0, 0, 0, 0, // z
+        ];
+        let replacement_number = calculate_replacement_number(&bingpai, &None);
+        assert!(matches!(
+            replacement_number.unwrap_err(),
+            InvalidShoupaiError::InvalidBingpai(InvalidBingpaiError::InvalidNumBingpai(12))
         ));
     }
 
@@ -302,7 +348,35 @@ mod tests {
         let replacement_number = calculate_replacement_number_3_player(&bingpai, &None);
         assert!(matches!(
             replacement_number.unwrap_err(),
-            InvalidShoupaiError::EmptyShoupai
+            InvalidShoupaiError::InvalidBingpai(InvalidBingpaiError::EmptyBingpai)
+        ));
+    }
+
+    #[test]
+    fn calculate_replacement_number_3_player_2m_8m() {
+        let bingpai_2m: Bingpai = [
+            0, 1, 0, 0, 0, 0, 0, 0, 0, // m
+            0, 0, 0, 0, 0, 0, 0, 0, 0, // p
+            0, 0, 0, 0, 0, 0, 0, 0, 0, // s
+            0, 0, 0, 0, 0, 0, 0, // z
+        ];
+        let bingpai_8m: Bingpai = [
+            0, 0, 0, 0, 0, 0, 0, 1, 0, // m
+            0, 0, 0, 0, 0, 0, 0, 0, 0, // p
+            0, 0, 0, 0, 0, 0, 0, 0, 0, // s
+            0, 0, 0, 0, 0, 0, 0, // z
+        ];
+
+        let replacement_number_2m = calculate_replacement_number_3_player(&bingpai_2m, &None);
+        let replacement_number_8m = calculate_replacement_number_3_player(&bingpai_8m, &None);
+
+        assert!(matches!(
+            replacement_number_2m.unwrap_err(),
+            InvalidShoupaiError::InvalidBingpai(InvalidBingpaiError::InvalidTileFor3Player(1))
+        ));
+        assert!(matches!(
+            replacement_number_8m.unwrap_err(),
+            InvalidShoupaiError::InvalidBingpai(InvalidBingpaiError::InvalidTileFor3Player(7))
         ));
     }
 }

src/fulu_mianzi.rs

@@ -103,6 +103,9 @@ pub enum InvalidFuluMianziError {
     /// The tile and position combination cannot form a valid sequence.
     #[error("a sequence cannot be made with {0} and {1:?}")]
     InvalidShunziCombination(Tile, ClaimedTilePosition),
+    /// This meld cannot be used in 3-player mahjong (2m to 8m or sequence).
+    #[error("{0} cannot be used in 3-player mahjong")]
+    InvalidFuluMianziFor3Player(FuluMianzi),
 }
 
 impl FuluMianzi {
@@ -132,6 +135,25 @@ impl FuluMianzi {
         }
     }
 
+    pub(crate) fn validate_3_player(&self) -> Result<(), InvalidFuluMianziError> {
+        match self {
+            FuluMianzi::Shunzi(_, _) => {
+                return Err(InvalidFuluMianziError::InvalidFuluMianziFor3Player(
+                    self.clone(),
+                ));
+            }
+            FuluMianzi::Kezi(t) | FuluMianzi::Gangzi(t) => {
+                if (1..8).contains(t) {
+                    return Err(InvalidFuluMianziError::InvalidFuluMianziFor3Player(
+                        self.clone(),
+                    ));
+                }
+            }
+        }
+
+        self.validate()
+    }
+
     #[inline]
     fn is_valid_shunzi_combination(tile: &Tile, position: &ClaimedTilePosition) -> bool {
         match position {

src/lib.rs

@@ -50,7 +50,7 @@ mod shoupai;
 mod standard;
 
 #[cfg(not(feature = "build-file"))]
-pub use bingpai::Bingpai;
+pub use bingpai::{Bingpai, InvalidBingpaiError};
 #[cfg(not(feature = "build-file"))]
 pub use calculate::{calculate_replacement_number, calculate_replacement_number_3_player};
 #[cfg(not(feature = "build-file"))]