Skip to main content

hearts_engine/
view.rs

1//! The [`View`]: what one seat may legally see of a round
2//!
3//! [`Round`](hearts::Round) exposes the whole position — all four hands and
4//! every pass — and leaves information hygiene to its consumers.  This
5//! module is that hygiene: a [`View`] borrows the round privately and
6//! re-exposes only the whitelist of legally visible information.
7//!
8//! Unlike gin rummy, everything a Hearts seat may know is derivable from
9//! the public history the round already retains, so there is no hidden
10//! per-seat ledger: the only cached inference is the common-knowledge void
11//! table that the [`Table`](crate::Table) maintains (a seat that does not
12//! follow suit is void in the led suit, in front of everyone).
13
14use hearts::{Hand, PassDirection, Phase, Round, Rules, Seat, Suit, Trick};
15
16/// What one seat may legally see of a round
17///
18/// The wrapped [`Round`] is private, and these accessors are the whitelist:
19/// the other hands and the pre-exchange passes are structurally
20/// unreachable.
21pub struct View<'a> {
22    round: &'a Round,
23    seat: Seat,
24    /// Common-knowledge voids: bit `suit as u8` of `voids[seat as usize]`.
25    voids: &'a [u8; 4],
26    /// Running game totals, clockwise from this seat.
27    scores: [u16; 4],
28}
29
30impl<'a> View<'a> {
31    pub(crate) const fn new(
32        round: &'a Round,
33        seat: Seat,
34        voids: &'a [u8; 4],
35        scores: [u16; 4],
36    ) -> Self {
37        Self {
38            round,
39            seat,
40            voids,
41            scores,
42        }
43    }
44
45    /// The seat this view belongs to
46    #[must_use]
47    pub const fn seat(&self) -> Seat {
48        self.seat
49    }
50
51    /// The running game totals, clockwise from this seat:
52    /// `[mine, my left, across, my right]`
53    ///
54    /// Note the order: seat-relative, unlike [`Table::scores`], which is
55    /// indexed by [`Seat`].  All totals sit on the scoreboard in plain
56    /// sight, so they are part of the legal whitelist.  `[0; 4]` for a
57    /// standalone round played outside a [`Game`](hearts::Game); the losing
58    /// threshold is [`rules().game_target`](hearts::Rules::game_target).
59    ///
60    /// [`Table::scores`]: crate::Table::scores
61    #[must_use]
62    pub const fn game_scores(&self) -> [u16; 4] {
63        self.scores
64    }
65
66    /// The rules of the round
67    #[must_use]
68    pub const fn rules(&self) -> &'a Rules {
69        self.round.rules()
70    }
71
72    /// The pass direction of the round
73    #[must_use]
74    pub const fn direction(&self) -> PassDirection {
75        self.round.direction()
76    }
77
78    /// The current phase of the round
79    #[must_use]
80    pub const fn phase(&self) -> Phase {
81        self.round.phase()
82    }
83
84    /// This seat's hand
85    #[must_use]
86    pub const fn hand(&self) -> Hand {
87        self.round.hand(self.seat)
88    }
89
90    /// The seat to play, or `None` outside the playing phase
91    #[must_use]
92    pub fn turn(&self) -> Option<Seat> {
93        self.round.turn()
94    }
95
96    /// The trick in progress; `Some` exactly during [`Phase::Playing`]
97    #[must_use]
98    pub const fn current_trick(&self) -> Option<Trick> {
99        self.round.current_trick()
100    }
101
102    /// The completed tricks in play order
103    #[must_use]
104    pub fn tricks(&self) -> &'a [Trick] {
105        self.round.tricks()
106    }
107
108    /// Every card played so far, including the trick in progress
109    #[must_use]
110    pub fn played(&self) -> Hand {
111        self.round.played()
112    }
113
114    /// Whether a heart has been played, allowing hearts to be led
115    #[must_use]
116    pub fn hearts_broken(&self) -> bool {
117        self.round.hearts_broken()
118    }
119
120    /// The cards this seat may legally play right now
121    ///
122    /// Empty when it is not this seat's turn.
123    #[must_use]
124    pub fn legal_plays(&self) -> Hand {
125        self.round.legal_plays(self.seat)
126    }
127
128    /// The penalty points `seat` has taken so far — public bookkeeping
129    #[must_use]
130    pub fn points_taken(&self, seat: Seat) -> u8 {
131        self.round.points_taken(seat)
132    }
133
134    /// How many cards `seat` holds — public arithmetic
135    #[must_use]
136    pub const fn hand_len(&self, seat: Seat) -> usize {
137        self.round.hand(seat).len()
138    }
139
140    /// The three cards this seat chose to pass, or `None` if it has not
141    /// passed (always `None` on a hold deal)
142    #[must_use]
143    pub const fn passed(&self) -> Option<Hand> {
144        self.round.passed(self.seat)
145    }
146
147    /// The three cards this seat received in the exchange
148    ///
149    /// `None` until the exchange happens and on hold deals — a seat never
150    /// sees incoming cards while passing is still open.
151    #[must_use]
152    pub fn received(&self) -> Option<Hand> {
153        match self.phase() {
154            Phase::Passing => None,
155            Phase::Playing | Phase::Finished => {
156                self.round.passed(self.direction().giver(self.seat))
157            }
158        }
159    }
160
161    /// Whether `seat` is known to be void in `suit`
162    ///
163    /// Void inference is common knowledge: everyone sees a seat fail to
164    /// follow.  The table is *sound, not complete* — it records only voids
165    /// shown in play, so it lags a seat's real hand (including this seat's
166    /// own; check `hand()[suit].is_empty()` for that).
167    #[must_use]
168    pub const fn is_void(&self, seat: Seat, suit: Suit) -> bool {
169        self.voids[seat as usize] & 1 << suit as u8 != 0
170    }
171
172    /// The unplayed cards this seat *knows* `seat` holds: the passed cards
173    /// still in the receiver's hand
174    ///
175    /// Empty for every seat other than this seat's
176    /// [receiver](PassDirection::receiver), and before the exchange.
177    #[must_use]
178    pub fn known_cards(&self, seat: Seat) -> Hand {
179        let receiver = self.direction().receiver(self.seat);
180        if seat != self.seat && seat == receiver && self.phase() != Phase::Passing {
181            self.passed()
182                .map_or(Hand::EMPTY, |passed| passed - self.played())
183        } else {
184            Hand::EMPTY
185        }
186    }
187
188    /// The cards this seat cannot locate: the whole deck minus its own
189    /// hand, everything played, and its own passed cards
190    ///
191    /// Exactly the cards a determinizing bot must distribute among the
192    /// other hands.  Once play begins, `unseen().len()` equals the other
193    /// hands' total minus the cards [`known_cards`](Self::known_cards)
194    /// already places.  During the passing phase the identity is offset by
195    /// passes in flight — a seat that has passed holds 10 cards while its
196    /// 3 hidden passes stay unseen — so a pass-time determinizer should
197    /// sample 13-card *pre-pass* hands instead.
198    #[must_use]
199    pub fn unseen(&self) -> Hand {
200        Hand::ALL - self.hand() - self.played() - self.passed().unwrap_or(Hand::EMPTY)
201    }
202
203    /// The cards `seat` may hold, as far as this seat can tell
204    ///
205    /// This seat's own hand for itself; otherwise the unseen cards outside
206    /// `seat`'s known voids, plus the [`known_cards`](Self::known_cards).
207    #[must_use]
208    pub fn possible_cards(&self, seat: Seat) -> Hand {
209        if seat == self.seat {
210            return self.hand();
211        }
212        let mut cards = self.unseen();
213        for suit in Suit::ASC {
214            if self.is_void(seat, suit) {
215                cards[suit] = hearts::Holding::EMPTY;
216            }
217        }
218        cards | self.known_cards(seat)
219    }
220}