kevy-time 5.4.0

Pure calendar arithmetic on epoch seconds: civil conversion, month-clamped addition, and the @-expression evaluator query bounds use.
Documentation
//! Pure calendar arithmetic on epoch seconds — the date-arithmetic
//! stone (R4a's last engine-side gap). Time columns stay declared
//! i64 (epoch seconds; units belong to the caller, the WINDOW
//! philosophy) — this crate is the query-side arithmetic that turns
//! a human bound into that i64, never a new column type.
//!
//! Everything here is a pure function: `now` is always an argument,
//! the stone never touches a clock. Proleptic Gregorian, UTC only
//! (zone conversion is the application's — refused by name at the
//! surface, not silently guessed here).
//!
//! The civil conversion is the standard integer-arithmetic algorithm
//! (era/year-of-era/day-of-year decomposition over 400-year cycles),
//! exact over the whole i64 day range the epoch can reach.

#![forbid(unsafe_code)]

const SECS_PER_DAY: i64 = 86_400;

/// One civil timestamp: year, month (1-12), day (1-31), hour,
/// minute, second — UTC, proleptic Gregorian.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Civil {
    /// Year (proleptic Gregorian; negative epochs decode correctly).
    pub y: i64,
    /// Month, 1-12.
    pub m: u32,
    /// Day of month, 1-31.
    pub d: u32,
    /// Hour, 0-23.
    pub h: u32,
    /// Minute, 0-59.
    pub min: u32,
    /// Second, 0-59.
    pub s: u32,
}

/// Days since the epoch for a civil date.
fn days_from_civil(y: i64, m: u32, d: u32) -> i64 {
    let y = if m <= 2 { y - 1 } else { y };
    let era = if y >= 0 { y } else { y - 399 } / 400;
    let yoe = y - era * 400;
    let mp = i64::from(if m > 2 { m - 3 } else { m + 9 });
    let doy = (153 * mp + 2) / 5 + i64::from(d) - 1;
    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
    era * 146_097 + doe - 719_468
}

/// Civil date for days since the epoch.
fn civil_from_days(z: i64) -> (i64, u32, u32) {
    let z = z + 719_468;
    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
    let doe = z - era * 146_097;
    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
    let y = yoe + era * 400;
    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
    let mp = (5 * doy + 2) / 153;
    let d = (doy - (153 * mp + 2) / 5 + 1) as u32;
    let m = (if mp < 10 { mp + 3 } else { mp - 9 }) as u32;
    (if m <= 2 { y + 1 } else { y }, m, d)
}

/// Decode epoch seconds to a civil timestamp.
pub fn civil_from_epoch(secs: i64) -> Civil {
    let days = secs.div_euclid(SECS_PER_DAY);
    let rem = secs.rem_euclid(SECS_PER_DAY) as u32;
    let (y, m, d) = civil_from_days(days);
    Civil { y, m, d, h: rem / 3600, min: rem / 60 % 60, s: rem % 60 }
}

/// Encode a civil timestamp to epoch seconds. The caller supplies
/// in-range fields; out-of-range months/days would decode to a
/// different date, which is why the parser validates before calling.
pub fn epoch_from_civil(c: Civil) -> i64 {
    days_from_civil(c.y, c.m, c.d) * SECS_PER_DAY
        + i64::from(c.h) * 3600
        + i64::from(c.min) * 60
        + i64::from(c.s)
}

/// The last day of a month (leap-aware).
fn last_day(y: i64, m: u32) -> u32 {
    match m {
        1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
        4 | 6 | 9 | 11 => 30,
        _ => {
            if y % 4 == 0 && (y % 100 != 0 || y % 400 == 0) {
                29
            } else {
                28
            }
        }
    }
}

/// Add `n` calendar months (negative subtracts), clamping the day to
/// the target month's end — Jan 31 + 1mo = Feb 28 (29 in a leap
/// year), the convention every calendar API converges on.
pub fn add_months(secs: i64, n: i64) -> i64 {
    let c = civil_from_epoch(secs);
    let months = c.y * 12 + i64::from(c.m) - 1 + n;
    let (y, m) = (months.div_euclid(12), (months.rem_euclid(12) + 1) as u32);
    let d = c.d.min(last_day(y, m));
    epoch_from_civil(Civil { y, m, d, ..c })
}

/// Evaluate one `@` query-bound expression against the caller's
/// `now`. `None` on anything malformed — the surface refuses by
/// name, this stone never guesses.
///
/// Grammar: `@now`, `@now±<n><unit>` with unit s|m|h|d|w (plain
/// second arithmetic) or mo|y (calendar months via [`add_months`]),
/// `@YYYY-MM-DD` (midnight) and `@YYYY-MM-DDThh:mm:ss`.
pub fn eval(expr: &[u8], now: i64) -> Option<i64> {
    let body = expr.strip_prefix(b"@")?;
    if let Some(rest) = body.strip_prefix(b"now") {
        if rest.is_empty() {
            return Some(now);
        }
        let (sign, rest) = match rest.first()? {
            b'+' => (1i64, &rest[1..]),
            b'-' => (-1i64, &rest[1..]),
            _ => return None,
        };
        let digits = rest.iter().take_while(|b| b.is_ascii_digit()).count();
        if digits == 0 {
            return None;
        }
        let n: i64 = std::str::from_utf8(&rest[..digits]).ok()?.parse().ok()?;
        return match &rest[digits..] {
            b"s" => now.checked_add(sign * n),
            b"m" => now.checked_add(sign.checked_mul(n.checked_mul(60)?)?),
            b"h" => now.checked_add(sign.checked_mul(n.checked_mul(3600)?)?),
            b"d" => now.checked_add(sign.checked_mul(n.checked_mul(SECS_PER_DAY)?)?),
            b"w" => now.checked_add(sign.checked_mul(n.checked_mul(7 * SECS_PER_DAY)?)?),
            b"mo" => Some(add_months(now, sign * n)),
            b"y" => Some(add_months(now, sign.checked_mul(n.checked_mul(12)?)?)),
            _ => None,
        };
    }
    parse_literal(body)
}

/// `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss`, validated against the real
/// calendar (a Feb 30 is a refusal, not a wraparound).
fn parse_literal(b: &[u8]) -> Option<i64> {
    let num = |s: &[u8]| -> Option<i64> {
        (!s.is_empty() && s.iter().all(u8::is_ascii_digit))
            .then(|| std::str::from_utf8(s).ok()?.parse().ok())
            .flatten()
    };
    let (date, time) = match b.len() {
        10 => (b, None),
        19 => {
            if b[10] != b'T' {
                return None;
            }
            (&b[..10], Some(&b[11..]))
        }
        _ => return None,
    };
    if date[4] != b'-' || date[7] != b'-' {
        return None;
    }
    let (y, m, d) = (num(&date[..4])?, num(&date[5..7])? as u32, num(&date[8..10])? as u32);
    if !(1..=12).contains(&m) || d < 1 || d > last_day(y, m) {
        return None;
    }
    let (h, min, s) = match time {
        None => (0, 0, 0),
        Some(t) => {
            if t[2] != b':' || t[5] != b':' {
                return None;
            }
            let (h, min, s) = (num(&t[..2])? as u32, num(&t[3..5])? as u32, num(&t[6..8])? as u32);
            if h > 23 || min > 59 || s > 59 {
                return None;
            }
            (h, min, s)
        }
    };
    Some(epoch_from_civil(Civil { y, m, d, h, min, s }))
}

#[cfg(test)]
#[path = "lib_tests.rs"]
mod tests;