wowlab_types/types/sim/

time.rs

use serde::{Deserialize, Serialize};

/// Simulation time in milliseconds.
#[derive(
    Clone, Copy, Debug, Default, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize,
)]
#[serde(transparent)]
#[cfg_attr(feature = "wasm", derive(tsify::Tsify))]
#[cfg_attr(feature = "wasm", tsify(into_wasm_abi, from_wasm_abi))]
// docref:start des-sim-time-struct
// #t(rust_newtype_pub_field) transparent simulation-time wire type with established tuple construction
pub struct SimTime(pub u32);
// docref:end des-sim-time-struct

impl SimTime {
    pub const ZERO: SimTime = SimTime(0);
    pub const MAX: SimTime = SimTime(u32::MAX);

    const MS_PER_SEC: u32 = 1000;
    const MS_PER_SEC_F32: f32 = 1000.0;

    #[inline]
    #[must_use]
    pub const fn from_millis(ms: u32) -> Self {
        SimTime(ms)
    }

    #[inline]
    #[must_use]
    pub const fn from_secs(secs: u32) -> Self {
        SimTime(secs * Self::MS_PER_SEC)
    }

    #[inline]
    #[must_use]
    #[expect(
        clippy::cast_possible_truncation,
        clippy::cast_sign_loss,
        reason = "Rust float-to-int saturation is the established behavior for out-of-range times"
    )]
    pub fn from_secs_f32(secs: f32) -> Self {
        // Round to nearest: truncation made ms→secs→SimTime round-trips land 1ms
        // early (16.194s * 1000 = 16193.999…), which permanently stalled events
        // scheduled off f64-second slots (auto-attack swings, GCD ends).
        SimTime((secs * Self::MS_PER_SEC_F32).round() as u32)
    }

    #[inline]
    #[must_use]
    #[expect(
        clippy::cast_possible_truncation,
        clippy::cast_sign_loss,
        reason = "Rust float-to-int saturation is the established behavior for out-of-range times"
    )]
    pub fn from_secs_f64(secs: f64) -> Self {
        SimTime((secs * crate::constants::MS_PER_SECOND).round() as u32)
    }

    #[inline]
    #[must_use]
    pub const fn as_millis(&self) -> u32 {
        self.0
    }

    #[inline]
    #[must_use]
    #[expect(
        clippy::cast_precision_loss,
        reason = "f32 seconds are an explicitly lower-precision display and scheduling API"
    )]
    pub fn as_secs_f32(&self) -> f32 {
        // #t(rust_lossy_cast) millis u32 -> f32 is fine for display, max precision loss ~1ms at high values
        self.0 as f32 / Self::MS_PER_SEC_F32
    }

    #[inline]
    #[must_use]
    pub fn as_secs_f64(&self) -> f64 {
        f64::from(self.0) / crate::constants::MS_PER_SECOND
    }

    #[inline]
    #[must_use]
    pub const fn saturating_sub(self, other: SimTime) -> SimTime {
        SimTime(self.0.saturating_sub(other.0))
    }

    #[inline]
    #[must_use]
    pub const fn saturating_add(self, other: SimTime) -> SimTime {
        SimTime(self.0.saturating_add(other.0))
    }
}

impl std::ops::Add for SimTime {
    type Output = SimTime;
    #[inline]
    fn add(self, rhs: SimTime) -> SimTime {
        SimTime(self.0 + rhs.0)
    }
}

impl std::ops::Sub for SimTime {
    type Output = SimTime;
    #[inline]
    fn sub(self, rhs: SimTime) -> SimTime {
        SimTime(self.0 - rhs.0)
    }
}

impl std::ops::AddAssign for SimTime {
    #[inline]
    fn add_assign(&mut self, rhs: SimTime) {
        self.0 += rhs.0;
    }
}

impl std::ops::SubAssign for SimTime {
    #[inline]
    fn sub_assign(&mut self, rhs: SimTime) {
        self.0 -= rhs.0;
    }
}

#[cfg(test)]
mod tests {
    use googletest::prelude::*;
    use rstest::rstest;

    use super::*;

    #[gtest]
    #[rstest]
    #[case::zero(0, SimTime(0))]
    #[case::five(5, SimTime(5000))]
    fn from_secs(#[case] input: u32, #[case] expected: SimTime) -> Result<()> {
        verify_that!(SimTime::from_secs(input), eq(expected))
    }

    #[gtest]
    #[rstest]
    #[case::whole(1.5, SimTime(1500))]
    #[case::sub_milli(0.001, SimTime(1))]
    #[case::zero(0.0, SimTime(0))]
    fn from_secs_f64(#[case] input: f64, #[case] expected: SimTime) -> Result<()> {
        verify_that!(SimTime::from_secs_f64(input), eq(expected))
    }

    #[gtest]
    #[rstest]
    #[case::whole(1.5, SimTime(1500))]
    #[case::sub_milli(0.001, SimTime(1))]
    #[case::zero(0.0, SimTime(0))]
    fn from_secs_f32(#[case] input: f32, #[case] expected: SimTime) -> Result<()> {
        verify_that!(SimTime::from_secs_f32(input), eq(expected))
    }

    #[gtest]
    #[rstest]
    #[case::whole(SimTime(1500), 1.5)]
    #[case::zero(SimTime(0), 0.0)]
    fn as_secs_f64(#[case] input: SimTime, #[case] expected: f64) -> Result<()> {
        verify_that!(input.as_secs_f64(), near(expected, 1e-9))
    }

    #[gtest]
    #[rstest]
    #[case::whole(SimTime(1500), 1.5)]
    #[case::zero(SimTime(0), 0.0)]
    fn as_secs_f32(#[case] input: SimTime, #[case] expected: f32) -> Result<()> {
        verify_that!(input.as_secs_f32(), near(expected, 1e-4))
    }

    #[gtest]
    #[rstest]
    #[case::saturates(SimTime(u32::MAX), SimTime(1), SimTime(u32::MAX))]
    #[case::normal(SimTime(100), SimTime(50), SimTime(150))]
    fn saturating_add(
        #[case] a: SimTime,
        #[case] b: SimTime,
        #[case] expected: SimTime,
    ) -> Result<()> {
        verify_that!(a.saturating_add(b), eq(expected))
    }

    #[gtest]
    #[rstest]
    #[case::underflow_floor(SimTime(3), SimTime(10), SimTime(0))]
    #[case::normal(SimTime(10), SimTime(4), SimTime(6))]
    fn saturating_sub(
        #[case] a: SimTime,
        #[case] b: SimTime,
        #[case] expected: SimTime,
    ) -> Result<()> {
        verify_that!(a.saturating_sub(b), eq(expected))
    }

    #[gtest]
    fn operator_overloads() -> Result<()> {
        verify_that!(SimTime(10) + SimTime(5), eq(SimTime(15)))?;
        verify_that!(SimTime(10) - SimTime(4), eq(SimTime(6)))?;
        let mut t = SimTime(10);

        t += SimTime(5);
        verify_that!(t, eq(SimTime(15)))?;
        t -= SimTime(3);

        verify_that!(t, eq(SimTime(12)))
    }
}