contract_bridge/

auction.rs

//! Auction lingo: calls, legal-call enforcement, and the sequence of calls
//! that make up the bidding phase of a deal.
//!
//! [`Call`] is the exhaustive set of legal announcements during the bidding —
//! pass, double, redouble, or a [`Bid`]. [`Auction`] stores a sequence of
//! `Call`s and enforces the laws of duplicate bridge on each insertion,
//! reporting violations via [`IllegalCall`].
//!
//! [`RelativeVulnerability`] is a 2-bit set (WE / THEY) for vulnerability
//! viewed from one partnership's perspective. The four valid combinations are
//! exposed as the constants [`NONE`](RelativeVulnerability::NONE),
//! [`WE`](RelativeVulnerability::WE), [`THEY`](RelativeVulnerability::THEY),
//! and [`ALL`](RelativeVulnerability::ALL). [`AbsoluteVulnerability`] is the
//! perspective-free counterpart, naming the vulnerable side(s) as NS / EW.

use crate::{Bid, Penalty};
use core::borrow::Borrow;
use core::fmt::{self, Write as _};
use core::ops::Deref;
use core::str::FromStr;
use thiserror::Error;

/// Any legal announcement in the bidding stage
///
/// This enum is intentionally exhaustive: the laws of contract bridge define
/// exactly these call types, so no future variants are possible.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(
    feature = "serde",
    derive(serde_with::SerializeDisplay, serde_with::DeserializeFromStr)
)]
pub enum Call {
    /// A call indicating no wish to change the contract
    Pass,
    /// A call increasing penalties and bonuses for the contract
    Double,
    /// A call doubling the score to the previous double
    Redouble,
    /// A call proposing a contract
    Bid(Bid),
}

impl From<Bid> for Call {
    fn from(bid: Bid) -> Self {
        Self::Bid(bid)
    }
}

impl fmt::Display for Call {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Pass => f.write_char('P'),
            Self::Double => f.write_char('X'),
            Self::Redouble => f.write_str("XX"),
            Self::Bid(bid) => bid.fmt(f),
        }
    }
}

/// Error returned when parsing a [`Call`] fails
#[derive(Debug, Error, Clone, Copy, PartialEq, Eq)]
#[error("Invalid call: expected pass, double, redouble, or a bid like '1NT' or '3♠'")]
pub struct ParseCallError;

impl FromStr for Call {
    type Err = ParseCallError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_ascii_uppercase().as_str() {
            "-" | "P" | "PASS" => Ok(Self::Pass),
            "X" | "DBL" | "DOUBLE" => Ok(Self::Double),
            "XX" | "RDBL" | "REDOUBLE" => Ok(Self::Redouble),
            _ => s.parse::<Bid>().map(Self::Bid).map_err(|_| ParseCallError),
        }
    }
}

bitflags::bitflags! {
    /// Vulnerability of sides
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
    #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    pub struct RelativeVulnerability: u8 {
        /// We are vulnerable
        const WE = 1;
        /// Opponents are vulnerable
        const THEY = 2;
    }
}

impl RelativeVulnerability {
    /// No player is vulnerable
    pub const NONE: Self = Self::empty();
    /// All players are vulnerable
    pub const ALL: Self = Self::all();
}

impl fmt::Display for RelativeVulnerability {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self {
            Self::NONE => f.write_str("none"),
            Self::WE => f.write_str("we"),
            Self::THEY => f.write_str("they"),
            Self::ALL => f.write_str("both"),
            _ => unreachable!("RelativeVulnerability has only 4 valid bit combinations"),
        }
    }
}

/// Error returned when parsing a [`RelativeVulnerability`] fails
#[derive(Debug, Error, Clone, Copy, PartialEq, Eq)]
#[error("Invalid relative vulnerability: expected one of none, we, they, both, all")]
pub struct ParseRelativeVulnerabilityError;

impl FromStr for RelativeVulnerability {
    type Err = ParseRelativeVulnerabilityError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_ascii_lowercase().as_str() {
            "none" => Ok(Self::NONE),
            "we" => Ok(Self::WE),
            "they" => Ok(Self::THEY),
            "both" | "all" => Ok(Self::ALL),
            _ => Err(ParseRelativeVulnerabilityError),
        }
    }
}

bitflags::bitflags! {
    /// Vulnerability of the two partnerships, by compass direction
    ///
    /// The absolute counterpart of [`RelativeVulnerability`]: it names the
    /// vulnerable side(s) of a board as North-South / East-West, independent of
    /// any partnership's perspective. The four valid combinations are exposed
    /// as the constants [`NONE`](Self::NONE), [`NS`](Self::NS),
    /// [`EW`](Self::EW), and [`ALL`](Self::ALL).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
    #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
    pub struct AbsoluteVulnerability: u8 {
        /// North-South are vulnerable
        const NS = 1;
        /// East-West are vulnerable
        const EW = 2;
    }
}

impl AbsoluteVulnerability {
    /// No player is vulnerable
    pub const NONE: Self = Self::empty();
    /// All players are vulnerable
    pub const ALL: Self = Self::all();
}

impl fmt::Display for AbsoluteVulnerability {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self {
            Self::NONE => f.write_str("none"),
            Self::NS => f.write_str("ns"),
            Self::EW => f.write_str("ew"),
            Self::ALL => f.write_str("both"),
            _ => unreachable!("AbsoluteVulnerability has only 4 valid bit combinations"),
        }
    }
}

/// Error returned when parsing an [`AbsoluteVulnerability`] fails
#[derive(Debug, Error, Clone, Copy, PartialEq, Eq)]
#[error("Invalid vulnerability: expected one of none, ns, ew, both, all")]
pub struct ParseAbsoluteVulnerabilityError;

impl FromStr for AbsoluteVulnerability {
    type Err = ParseAbsoluteVulnerabilityError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_ascii_lowercase().as_str() {
            "none" => Ok(Self::NONE),
            "ns" => Ok(Self::NS),
            "ew" => Ok(Self::EW),
            "both" | "all" => Ok(Self::ALL),
            _ => Err(ParseAbsoluteVulnerabilityError),
        }
    }
}

/// Types of illegal calls
///
/// The laws mentioned in the variants are from [The Laws of Duplicate Bridge
/// 2017][laws].
///
/// [laws]: http://www.worldbridge.org/wp-content/uploads/2017/03/2017LawsofDuplicateBridge-nohighlights.pdf
#[derive(Debug, Error, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
pub enum IllegalCall {
    /// Law 27: insufficient bid
    #[error("Law 27: insufficient bid")]
    InsufficientBid {
        /// The offending bid
        this: Bid,
        /// The last bid in the auction
        last: Option<Bid>,
    },

    /// Law 36: inadmissible doubles and redoubles
    #[error("Law 36: inadmissible doubles and redoubles")]
    InadmissibleDouble(Penalty),

    /// Law 39: call after the final pass
    #[error("Law 39: call after the final pass")]
    AfterFinalPass,
}

/// A sequence of [`Call`]s
#[derive(Debug, Clone, Default, PartialEq, Eq)]
#[cfg_attr(
    feature = "serde",
    derive(serde_with::SerializeDisplay, serde_with::DeserializeFromStr)
)]
pub struct Auction(Vec<Call>);

/// Format a sequence of calls as an auction: space-joined, with
/// [`Pass`](Call::Pass) rendered as `-` so [`Double`](Call::Double) /
/// [`Redouble`](Call::Redouble) stand out when scanning. A lone [`Call`]'s own
/// [`Display`](fmt::Display) still shows `P`; only the auction view substitutes
/// `-`. The `-` form round-trips through [`Call`]'s [`FromStr`].
pub fn display_calls(calls: &[Call]) -> impl fmt::Display + '_ {
    CallsAsAuction(calls)
}

struct CallsAsAuction<'a>(&'a [Call]);

impl fmt::Display for CallsAsAuction<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut iter = self.0.iter();
        if let Some(first) = iter.next() {
            write_call_in_auction(first, f)?;
            for call in iter {
                f.write_char(' ')?;
                write_call_in_auction(call, f)?;
            }
        }
        Ok(())
    }
}

/// Write one call in auction context: [`Pass`](Call::Pass) as `-`, everything
/// else via [`Call`]'s own [`Display`](fmt::Display).
fn write_call_in_auction(call: &Call, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    match call {
        Call::Pass => f.write_char('-'),
        other => fmt::Display::fmt(other, f),
    }
}

impl fmt::Display for Auction {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        display_calls(&self.0).fmt(f)
    }
}

/// Error returned when parsing an [`Auction`] fails
#[derive(Debug, Error, Clone, Copy, PartialEq, Eq)]
pub enum ParseAuctionError {
    /// A token could not be parsed as a [`Call`]
    #[error(transparent)]
    Call(#[from] ParseCallError),
    /// A parsed call would violate the laws of bidding
    #[error(transparent)]
    Illegal(#[from] IllegalCall),
}

impl FromStr for Auction {
    type Err = ParseAuctionError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let mut auction = Self::new();
        for token in s.split_ascii_whitespace() {
            auction.try_push(token.parse()?)?;
        }
        Ok(auction)
    }
}

/// View the auction as a slice of calls
impl Deref for Auction {
    type Target = [Call];

    fn deref(&self) -> &[Call] {
        &self.0
    }
}

impl AsRef<[Call]> for Auction {
    fn as_ref(&self) -> &[Call] {
        self
    }
}

impl Borrow<[Call]> for Auction {
    fn borrow(&self) -> &[Call] {
        self
    }
}

impl From<Auction> for Vec<Call> {
    fn from(auction: Auction) -> Self {
        auction.0
    }
}

impl IntoIterator for Auction {
    type Item = Call;
    type IntoIter = std::vec::IntoIter<Call>;

    fn into_iter(self) -> Self::IntoIter {
        self.0.into_iter()
    }
}

impl<'a> IntoIterator for &'a Auction {
    type Item = &'a Call;
    type IntoIter = core::slice::Iter<'a, Call>;

    fn into_iter(self) -> Self::IntoIter {
        self.0.iter()
    }
}

impl Auction {
    /// Construct an empty auction
    #[must_use]
    pub const fn new() -> Self {
        Self(Vec::new())
    }

    /// Check if the auction is terminated (by 3 consecutive passes following
    /// a call)
    #[must_use]
    pub fn has_ended(&self) -> bool {
        self.len() >= 4 && self[self.len() - 3..] == [Call::Pass; 3]
    }

    /// Test doubling the last bid
    fn can_double(&self) -> Result<(), IllegalCall> {
        let admissible = self
            .iter()
            .rev()
            .copied()
            .enumerate()
            .find(|&(_, call)| call != Call::Pass)
            .is_some_and(|(index, call)| index & 1 == 0 && matches!(call, Call::Bid(_)));

        if !admissible {
            return Err(IllegalCall::InadmissibleDouble(Penalty::Doubled));
        }
        Ok(())
    }

    /// Test redoubling the last double (dry run)
    fn can_redouble(&self) -> Result<(), IllegalCall> {
        let admissible = self
            .iter()
            .rev()
            .copied()
            .enumerate()
            .find(|&(_, call)| call != Call::Pass)
            .is_some_and(|(index, call)| index & 1 == 0 && call == Call::Double);

        if !admissible {
            return Err(IllegalCall::InadmissibleDouble(Penalty::Redoubled));
        }
        Ok(())
    }

    /// Test bidding a contract (dry run)
    fn can_bid(&self, bid: Bid) -> Result<(), IllegalCall> {
        let last = self.iter().rev().find_map(|&call| match call {
            Call::Bid(bid) => Some(bid),
            _ => None,
        });

        if last >= Some(bid) {
            return Err(IllegalCall::InsufficientBid { this: bid, last });
        }
        Ok(())
    }

    /// Test adding a call to the auction (dry run)
    ///
    /// This is the check behind [`try_push`][Self::try_push] without the push,
    /// for filtering candidate calls without cloning the auction.
    ///
    /// # Errors
    ///
    /// [`IllegalCall`] if the call is forbidden by [The Laws of Duplicate
    /// Bridge][laws].
    ///
    /// [laws]: http://www.worldbridge.org/wp-content/uploads/2017/03/2017LawsofDuplicateBridge-nohighlights.pdf
    pub fn can_push(&self, call: Call) -> Result<(), IllegalCall> {
        if self.has_ended() {
            return Err(IllegalCall::AfterFinalPass);
        }

        match call {
            Call::Pass => Ok(()),
            Call::Double => self.can_double(),
            Call::Redouble => self.can_redouble(),
            Call::Bid(bid) => self.can_bid(bid),
        }
    }

    /// Add a call to the auction
    ///
    /// # Panics
    ///
    /// Panics if the call is illegal.
    pub fn push(&mut self, call: Call) {
        self.try_push(call).unwrap();
    }

    /// Add a call to the auction with checks
    ///
    /// # Errors
    ///
    /// [`IllegalCall`] if the call is forbidden by [The Laws of Duplicate
    /// Bridge][laws].
    ///
    /// [laws]: http://www.worldbridge.org/wp-content/uploads/2017/03/2017LawsofDuplicateBridge-nohighlights.pdf
    pub fn try_push(&mut self, call: Call) -> Result<(), IllegalCall> {
        self.can_push(call)?;
        self.0.push(call);
        Ok(())
    }

    /// Try adding calls to the auction
    ///
    /// # Errors
    ///
    /// If any call is illegal, an [`IllegalCall`] is returned.  Calls already
    /// added to the auction are kept.  If you want to roll back the auction,
    /// [`truncate`][Self::truncate] it to the previous length.
    pub fn try_extend(&mut self, iter: impl IntoIterator<Item = Call>) -> Result<(), IllegalCall> {
        let iter = iter.into_iter();

        if let Some(size) = iter.size_hint().1 {
            self.0.reserve(size);
        }

        for call in iter {
            self.try_push(call)?;
        }
        Ok(())
    }

    /// Pop the last call from the auction
    pub fn pop(&mut self) -> Option<Call> {
        self.0.pop()
    }

    /// Truncate the auction to the first `len` calls
    ///
    /// If `len` is greater or equal to the current length, this has no effect.
    pub fn truncate(&mut self, len: usize) {
        self.0.truncate(len);
    }

    /// Find the position of the declaring bid in the call sequence
    ///
    /// The declarer is the first player on the declaring side to have bid the
    /// strain of the final contract.  This method returns the index of that
    /// bid in `self`, so `self[index]` is the declaring bid.
    ///
    /// The index also encodes the relative seat: `index % 2 == 0` is the
    /// dealer's side, and `index % 2 == 1` is the other side.  To obtain the
    /// absolute [`Seat`](crate::Seat), add the dealer's seat offset modulo 4.
    ///
    /// Returns [`None`] if the auction has no bid (passed out).
    ///
    /// # Examples
    ///
    /// ```
    /// use contract_bridge::auction::{Auction, Call, IllegalCall};
    /// use contract_bridge::{Bid, Level, Strain};
    ///
    /// # fn main() -> Result<(), IllegalCall> {
    /// // 1♥ by opener (index 1), raised to 4♥ — declarer bid 1♥ at index 1
    /// let mut auction = Auction::new();
    /// let one_heart = Call::Bid(Bid { level: Level::new(1), strain: Strain::Hearts });
    /// let four_hearts = Call::Bid(Bid { level: Level::new(4), strain: Strain::Hearts });
    /// auction.try_push(Call::Pass)?;  // index 0 (dealer)
    /// auction.try_push(one_heart)?;   // index 1 (declarer)
    /// auction.try_push(Call::Pass)?;  // index 2
    /// auction.try_push(four_hearts)?; // index 3 (dummy)
    /// auction.try_push(Call::Pass)?;
    /// auction.try_push(Call::Pass)?;
    /// auction.try_push(Call::Pass)?;
    /// assert_eq!(auction.declarer(), Some(1));
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn declarer(&self) -> Option<usize> {
        let (parity, strain) =
            self.iter()
                .copied()
                .enumerate()
                .rev()
                .find_map(|(index, call)| match call {
                    Call::Bid(bid) => Some((index & 1, bid.strain)),
                    _ => None,
                })?;

        self.iter()
            .skip(parity)
            .step_by(2)
            .position(|call| match call {
                Call::Bid(bid) => bid.strain == strain,
                _ => false,
            })
            .map(|position| position << 1 | parity)
    }
}

#[cfg(test)]
mod tests;