crabchess/positions/

timer.rs

//! This module exposes an incremental chess timer which can be used to track a chess player's time
//! remaining and move history and read and format PGN-style clock annotations.

#![allow(clippy::cast_precision_loss)]

use crate::{
    error::{Err, Result},
    pieces::Color::{self, Black, White},
};
use compact_str::{format_compact, CompactString};
use std::{collections::BTreeMap, str::FromStr};

/// Struct to hold both players' timers in a game of chess.
#[derive(Clone, Debug)]
pub struct Timers {
    pub white: Timer,
    pub black: Timer,
}

impl Timers {
    /// Create timers with given time controls.
    #[must_use]
    pub fn new(allocated: u32, increment: u32) -> Self {
        Self {
            white: Timer::new(allocated, increment),
            black: Timer::new(allocated, increment),
        }
    }

    /// Get PGN tag.
    ///
    /// # Errors
    ///
    /// Returns an error if `White` and `Black` have different time controls.
    pub fn pgn_tag(&self) -> Result<String> {
        if self.white.allocated != self.black.allocated
            || self.white.increment != self.black.increment
        {
            return Err(Err::DifferentTimeControlsError(
                self.white.clone(),
                self.black.clone(),
            ));
        }

        Ok(self.white.pgn_tag())
    }

    /// Get reference to timer by color.
    #[must_use]
    pub const fn get(&self, color: Color) -> &Timer {
        match color {
            White => &self.white,
            Black => &self.black,
        }
    }

    /// Get mutable reference to timer by color.
    pub fn get_mut(&mut self, color: Color) -> &mut Timer {
        match color {
            White => &mut self.white,
            Black => &mut self.black,
        }
    }

    /// Get value from history, regardless of color.
    #[must_use]
    pub fn get_history(&self, ply_number: &u16) -> Option<&f32> {
        self.white
            .history
            .get(ply_number)
            .or_else(|| self.black.history.get(ply_number))
    }
}

/// An incremental chess timer. The value in `allocated` represents the initial time in seconds a
/// player has on the clock. After each move, the clock will decrement by the time elapsed during
/// the move and increment by the value in `increment`.
#[derive(Clone)]
pub struct Timer {
    pub allocated: u32,
    pub increment: u32,
    pub remaining: f32,
    /// Timer history is recorded in a hash table with ply number keys and seconds remaining as
    /// values.
    pub history: BTreeMap<u16, f32>,
}

impl core::fmt::Debug for Timer {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "Timer(allocated={}, increment={}, remaining={})",
            self.allocated, self.increment, self.remaining
        )
    }
}

impl Timer {
    /// Create a timer with `allocated` and `increment` values.
    #[must_use]
    pub const fn new(allocated: u32, increment: u32) -> Self {
        Self {
            allocated,
            increment,
            remaining: allocated as f32,
            history: BTreeMap::new(),
        }
    }

    /// Create a timer from a time control PGN header formatted like `"300+5"` or `"1200"`.
    ///
    /// # Errors
    ///
    /// Returns an error if time controls do not match the format.
    pub fn from_pgn_tag(controls: &str) -> Result<Self> {
        let (allocated, increment) = Self::read_control(controls)?;

        Ok(Self::new(allocated, increment))
    }

    /// Write a PGN tag representing the timer's time controls.
    #[must_use]
    pub fn pgn_tag(&self) -> String {
        let mut output = format!("{}", self.allocated);

        if self.increment > 0 {
            output.push_str(&format!("+{}", self.increment));
        }

        output
    }

    /// Set to 0 seconds remaining.
    pub fn zero(&mut self) {
        self.remaining = 0.0;
    }

    /// Read a time control formatted like: `"300+5"`.
    ///
    /// # Errors
    ///
    /// Returns an error if time controls do not match the format.
    pub fn read_control(controls: &str) -> Result<(u32, u32)> {
        let allocated: &str;
        let increment: &str;

        if let Some(tup) = controls.split_once('+') {
            (allocated, increment) = tup;
        } else {
            (allocated, increment) = (controls, "0");
        }

        let Ok(allocated) = allocated.parse() else {
            return Err(Err::ParseError("allocated", allocated.into()));
        };
        let Ok(increment) = increment.parse() else {
            return Err(Err::ParseError("increment", increment.into()));
        };

        Ok((allocated, increment))
    }

    /// Add a move to the timer, updating fields `seconds_remaining` and `history`.
    pub fn update(&mut self, ply_number: u16, update: Update) {
        match update {
            Update::ElapsedInMove(elapsed) => {
                self.remaining -= elapsed;

                if self.remaining > 0.0 {
                    self.remaining += self.increment as f32;
                } else if self.remaining < 0.0 {
                    self.remaining = 0.0;
                }
            }
            Update::Remaining(remaining) => self.remaining = remaining,
        }

        self.history.insert(ply_number, self.remaining);
    }

    /// Write a clock annotation from the current `seconds_remaining` value.
    #[must_use]
    pub fn annotation(&self) -> CompactString {
        Update::write_annotation(self.remaining)
    }

    /// Return a `bool` representing whether the clock has run out.
    #[must_use]
    pub fn timeout(&self) -> bool {
        self.remaining == 0.0
    }
}

impl FromStr for Timer {
    type Err = Err;

    fn from_str(s: &str) -> std::prelude::v1::Result<Self, Self::Err> {
        Self::from_pgn_tag(s)
    }
}

impl TryFrom<&str> for Timer {
    type Error = Err;

    fn try_from(value: &str) -> std::prelude::v1::Result<Self, Self::Error> {
        Self::from_pgn_tag(value)
    }
}

/// An update to a chess timer, based either on the new total seconds remaining or the seconds
/// elapsed during the turn.
#[derive(Debug, PartialEq, PartialOrd, Clone, Copy)]
pub enum Update {
    ElapsedInMove(f32),
    Remaining(f32),
}

impl Update {
    /// Reads a clock annotation in `[%clk 0:00:00.0]` format, returning `Self::Remaining`.
    ///
    /// # Errors
    ///
    /// Returns an error if annotation does not match format.
    pub fn read_annotation(annotation: &str) -> Result<Self> {
        let mut as_str = annotation;
        if let Some(stripped) = as_str.strip_prefix("[%clk ") {
            as_str = stripped;
        }
        if let Some(stripped) = as_str.strip_suffix(']') {
            as_str = stripped;
        }
        let mut split_str = as_str.split(':');

        let Some(hours_str) = split_str.next() else {
            return Err(Err::ParseError("timer annotation", annotation.into()));
        };
        let Ok(hours) = hours_str.parse::<f32>() else {
            return Err(Err::ParseError("timer annotation", annotation.into()));
        };

        let Some(minutes_str) = split_str.next() else {
            return Err(Err::ParseError("timer annotation", annotation.into()));
        };
        let Ok(minutes) = minutes_str.parse::<f32>() else {
            return Err(Err::ParseError("timer annotation", annotation.into()));
        };

        let Some(seconds_str) = split_str.next() else {
            return Err(Err::ParseError("timer annotation", annotation.into()));
        };
        let Ok(seconds) = seconds_str.parse::<f32>() else {
            return Err(Err::ParseError("timer annotation", annotation.into()));
        };

        Ok(Self::Remaining(
            hours.mul_add(3600.0, minutes * 60.0) + seconds,
        ))
    }

    /// Writes a clock annotation in `[%clk 0:00:00.0]` format.
    #[must_use]
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    pub fn write_annotation(time: f32) -> CompactString {
        let mut parts: f32 = time;

        let hours = (parts / 3600.0).floor() as usize;
        parts %= 3600.0;

        let minutes = (parts / 60.0).floor() as u8;
        parts %= 60.0;

        format_compact!("[%clk {hours}:{minutes:02}:{parts:04.1}]")
    }

    /// Get an update's floating-point value.
    #[must_use]
    pub const fn value(&self) -> f32 {
        let (Self::ElapsedInMove(r) | Self::Remaining(r)) = self;
        *r
    }
}

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

    #[test]
    fn update_timer() {
        let mut timer = Timer::new(400, 20);
        timer.update(5, Update::ElapsedInMove(53.456));
        assert_eq!(timer.remaining, 366.544);
    }

    #[test]
    fn make_annotation() {
        let mut timer = Timer::new(400, 20);
        timer.update(5, Update::ElapsedInMove(53.456));
        assert_eq!("[%clk 0:06:06.5]", timer.annotation());
    }

    #[test]
    fn test_read_annotation() {
        assert_eq!(
            [366.5, 11532.2, 7203.2, 0.0],
            [
                "[%clk 0:06:06.5]",
                "3:12:12.2",
                "[%clk 2:00:03.2]",
                "0:00:00.0",
            ]
            .map(|ann| {
                let Update::Remaining(val) = Update::read_annotation(ann).unwrap() else {
                    panic!("Expected Update::Remaining")
                };

                val
            })
        );
    }

    #[test]
    fn test_write_annotation() {
        assert_eq!(
            [366.5, 11532.2, 7203.2, 0.0].map(Update::write_annotation),
            [
                "[%clk 0:06:06.5]",
                "[%clk 3:12:12.2]",
                "[%clk 2:00:03.2]",
                "[%clk 0:00:00.0]",
            ]
        );
    }
}