bowling 0.2.0

A generic, typestate-driven bowling game engine
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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

//! Completed frame representation.

use super::FrameNumber;
use crate::roll::Roll;

// ---------------------------------------------------------------------------
// FrameKind
// ---------------------------------------------------------------------------

/// The classification of a completed frame.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FrameKind {
    /// First-ball clearance of all pins.
    Strike,
    /// All pins cleared within the allowed balls (but not the first ball).
    /// For duckpin, clearing with all 3 balls is [`FrameKind::AllDown`], not
    /// a spare.
    Spare,
    /// All pins cleared using all allowed balls in a variant where this does
    /// **not** earn a spare bonus (duckpin "ten").
    AllDown,
    /// Not all pins were knocked down.
    Open,
}

// ---------------------------------------------------------------------------
// FramePosition
// ---------------------------------------------------------------------------

/// Whether a frame is a regular (non-final) frame or the final frame.
///
/// Replaces a bare `bool` with a self-documenting enum so that call sites
/// read `FramePosition::Final` instead of `true`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum FramePosition {
    /// A regular (non-final) frame.
    Regular,
    /// The final frame of the game (with fill-ball rules).
    Final,
}

impl FramePosition {
    /// Returns `true` if this is the final frame.
    #[inline]
    pub const fn is_final(self) -> bool {
        matches!(self, Self::Final)
    }
}

// ---------------------------------------------------------------------------
// ScoredFrame
// ---------------------------------------------------------------------------

/// A completed frame with its deliveries recorded.
///
/// The cumulative score is computed separately by the scoring engine, which
/// needs lookahead into future frames for bonus calculations.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ScoredFrame {
    /// The frame number (1-indexed).
    number: FrameNumber,
    /// Whether this is a regular or final frame.
    position: FramePosition,
    /// The kind of result.
    kind: FrameKind,
    /// All deliveries in the frame (1–3 for regular, up to 3 for final).
    rolls: Vec<Roll>,
    /// Base pin count for this frame (sum of roll scores, before bonuses).
    base_score: u16,
}

impl ScoredFrame {
    /// Creates a new completed frame.
    pub(crate) fn new(
        number: FrameNumber,
        position: FramePosition,
        kind: FrameKind,
        rolls: Vec<Roll>,
        base_score: u16,
    ) -> Self {
        Self {
            number,
            position,
            kind,
            rolls,
            base_score,
        }
    }

    /// Returns the frame number (1-indexed).
    pub fn number(&self) -> FrameNumber {
        self.number
    }

    /// Returns the position of this frame (regular or final).
    pub fn position(&self) -> FramePosition {
        self.position
    }

    /// Returns `true` if this was the final frame of the game.
    pub fn is_final(&self) -> bool {
        self.position.is_final()
    }

    /// Returns the classification of this frame (strike, spare, open, etc.).
    pub fn kind(&self) -> FrameKind {
        self.kind
    }

    /// Returns the deliveries recorded in this frame.
    pub fn rolls(&self) -> &[Roll] {
        &self.rolls
    }

    /// Returns the base pin count for this frame (before bonuses).
    pub fn base_score(&self) -> u16 {
        self.base_score
    }

    /// How many future bonus deliveries this frame earns.
    pub fn bonus_balls(&self, strike_bonus: u8, spare_bonus: u8) -> u8 {
        match self.kind {
            FrameKind::Strike => {
                if self.position.is_final() {
                    0
                } else {
                    strike_bonus
                }
            }
            FrameKind::Spare => {
                if self.position.is_final() {
                    0
                } else {
                    spare_bonus
                }
            }
            FrameKind::AllDown | FrameKind::Open => 0,
        }
    }
}