ek_data/

time.rs

//! 零依赖时间面:纪元纳秒 ↔ civil(年月日时分秒)双向换算。
//!
//! Python 版 `TickData.datetime` 等字段用本地 naive `datetime`;
//! Rust 版统一为 **UTC 纪元纳秒**([`DtNs`]),本地化/展示层由使用方处理
//! (DESIGN.md 决定 8-A)。换算采用 Howard Hinnant 的 civil_from_days /
//! days_from_civil 算法(公历 1582-10-15 起全域正确),均以单测钉死。
//!
//! ## 可表达范围(重要)
//!
//! `DtNs = i64` 纳秒 → 覆盖 **1677-09-21T00:12:43.145224192Z ..
//! 2262-04-11T23:47:16.854775807Z**([`DTNS_MIN`]/[`DTNS_MAX`])。
//! 超出范围时[`try_civil_to_nanos`] 返回 `None`,[`civil_to_nanos`] panic
//! (对齐 Python `datetime` 超范围抛 `ValueError` 的失败面);
//! 远日期(如股票 IPO 日 1990 前 / 交易所属历史日期)请用 [`Day`] 序数表达。

use std::time::{SystemTime, UNIX_EPOCH};

/// 一秒的纳秒数。
pub const NANOS_PER_SEC: i64 = 1_000_000_000;
/// 一天的纳秒数(86400 s,不涉闰秒)。
pub const NANOS_PER_DAY: i64 = 86_400 * NANOS_PER_SEC;

/// `DtNs` 可表达的 civil 下界近似:1677-09-21T00:12:43.145224192Z
/// (即 `i64::MIN` 纳秒;换算取整到纳秒需 +1 才落在合法 civil 上)。
pub const DTNS_MIN: DtNs = i64::MIN;
/// `DtNs` 可表达的 civil 上界:2262-04-11T23:47:16.854775807Z。
pub const DTNS_MAX: DtNs = i64::MAX;

/// 时间戳:Unix 纪元(The Epoch, 1970-01-01T00:00:00Z)起的纳秒。
pub type DtNs = i64;

/// 交易日序数:Unix 纪元起的天数(向下取整,含负数)。
pub type Day = i32;

/// civil 纪元日天数 → 纪元日序数(Hinnant days_from_civil)。
///
/// 公历,"March through February" 换年修正。
pub fn days_from_civil(y: i32, m: u32, d: u32) -> Day {
    let y = if m <= 2 { y - 1 } else { y } as i64;
    let era = if y >= 0 { y } else { y - 399 } / 400;
    let yoe = y - era * 400; // [0, 399]
    let mp: i64 = ((m as i64) + 9) % 12; // [0, 11]: Mar = 0
    let doy = (153 * mp + 2) / 5 + (d as i64) - 1; // [0, 365]
    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy; // [0, 146096]
    (era * 146097 + doe - 719468) as Day
}

/// 纪元日序数 → civil (年, 月, 日)(Hinnant civil_from_days)。
pub fn civil_from_days(z: Day) -> (i32, u32, u32) {
    let z = z as i64 + 719468;
    let era = if z >= 0 { z } else { z - 146096 } / 146097;
    let doe = z - era * 146097; // [0, 146096]
    let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365; // [0, 399]
    let y = yoe + era * 400;
    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); // [0, 365]
    let mp = (5 * doy + 2) / 153; // [0, 11]
    let d = (doy - (153 * mp + 2) / 5 + 1) as u32; // [1, 31]
    let m = (if mp < 10 { mp + 3 } else { mp - 9 }) as u32; // [1, 12]
    ((y + if m <= 2 { 1 } else { 0 }) as i32, m, d)
}

/// civil 六元组 + 毫微段(一日内)。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Civil {
    /// 年(可为负)
    pub year: i32,
    /// 月 [1, 12]
    pub month: u32,
    /// 日 [1, 31]
    pub day: u32,
    /// 时 [0, 23]
    pub hour: u32,
    /// 分 [0, 59]
    pub minute: u32,
    /// 秒 [0, 59]
    pub second: u32,
    /// 纳秒段 [0, 999999999]
    pub nanos: u32,
}

/// civil → 纪元纳秒(以 civil 视作 UTC,无时区移位)。
///
/// **输入越界即 panic**(月>12、2 月 30 日、纳秒段超 1e9、超出 [`DTNS_MAX`]
/// 范围等),对齐 Python `datetime` 抛 `ValueError` 的失败面;
/// 需要可失败路径请用 [`try_civil_to_nanos`]。
pub fn civil_to_nanos(c: Civil) -> DtNs {
    match try_civil_to_nanos(c) {
        Some(t) => t,
        None => panic!("civil 越界或超出 DtNs 可表达范围: {c:?}"),
    }
}

/// civil → 纪元纳秒的可失败版本;严格校验日历合法性(含闰年 2 月)与 i64 范围。
pub fn try_civil_to_nanos(c: Civil) -> Option<DtNs> {
    if !is_valid_civil(&c) {
        return None;
    }
    let days = days_from_civil(c.year, c.month, c.day) as i64;
    let secs_of_day = (c.hour as i64) * 3600 + (c.minute as i64) * 60 + c.second as i64;
    days.checked_mul(NANOS_PER_DAY)?
        .checked_add(secs_of_day.checked_mul(NANOS_PER_SEC)?)?
        .checked_add(c.nanos as i64)
}

/// 闰年判定(公历规则)。
pub fn is_leap_year(year: i32) -> bool {
    (year % 4 == 0 && year % 100 != 0) || year % 400 == 0
}

/// 某年某月的天数(月越界返回 0)。
pub fn days_in_month(year: i32, month: u32) -> u32 {
    match month {
        1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
        4 | 6 | 9 | 11 => 30,
        2 => {
            if is_leap_year(year) {
                29
            } else {
                28
            }
        }
        _ => 0,
    }
}

/// civil 合法性(月 1-12、日不超当月天数、时分秒纳秒在域内)。
pub fn is_valid_civil(c: &Civil) -> bool {
    (1..=12).contains(&c.month)
        && c.day >= 1
        && c.day <= days_in_month(c.year, c.month)
        && c.hour < 24
        && c.minute < 60
        && c.second < 60
        && c.nanos < 1_000_000_000
}

/// 解析 `"YYYY-MM-DD[ HH:MM[:SS[.fffffffff]]]"`(亦接受 `T` 分隔与纯日期)。
///
/// 例:`"2024-12-25 09:30:01"`、`"2024-12-25T09:30"`、`"2024-12-25"`。
/// 小数秒不足 9 位右补零(`".5"` = 500ms)。非法日期/时间一律 `None`。
pub fn parse_civil(s: &str) -> Option<DtNs> {
    let s = s.trim();
    let (date_str, time_str) = match s.split_once(['T', ' ']) {
        Some((d, t)) => (d, Some(t)),
        None => (s, None),
    };
    let mut date_parts = date_str.split('-');
    let year: i32 = date_parts.next()?.parse().ok()?;
    let month: u32 = date_parts.next()?.parse().ok()?;
    let day: u32 = date_parts.next()?.parse().ok()?;
    if date_parts.next().is_some() {
        return None;
    }

    let (hour, minute, second, nanos) = match time_str {
        None => (0, 0, 0, 0),
        Some(t) => {
            let (hms, frac) = match t.split_once('.') {
                Some((a, b)) => (a, Some(b)),
                None => (t, None),
            };
            let mut it = hms.split(':');
            let hour: u32 = it.next()?.parse().ok()?;
            let minute: u32 = it.next().unwrap_or("0").parse().ok()?;
            let second: u32 = it.next().unwrap_or("0").parse().ok()?;
            if it.next().is_some() {
                return None;
            }
            let nanos = match frac {
                None => 0,
                Some(f) => {
                    if f.is_empty() || f.len() > 9 || !f.bytes().all(|b| b.is_ascii_digit()) {
                        return None;
                    }
                    let v: u32 = f.parse().ok()?;
                    v * 10u32.pow(9 - f.len() as u32)
                }
            };
            (hour, minute, second, nanos)
        }
    };

    try_civil_to_nanos(Civil {
        year,
        month,
        day,
        hour,
        minute,
        second,
        nanos,
    })
}

/// 纪元纳秒 → civil(UTC 视角;除法对负纳秒采用 floor 保证越日正确)。
pub fn civil_from_nanos(t: DtNs) -> Civil {
    let days = t.div_euclid(NANOS_PER_DAY);
    let secs_of_day = t.rem_euclid(NANOS_PER_DAY);
    let (year, month, day) = civil_from_days(days as Day);
    let total_sec = secs_of_day / NANOS_PER_SEC;
    let nanos = (secs_of_day % NANOS_PER_SEC) as u32;
    Civil {
        year,
        month,
        day,
        hour: (total_sec / 3600) as u32,
        minute: (total_sec % 3600 / 60) as u32,
        second: (total_sec % 60) as u32,
        nanos,
    }
}

/// 当前时刻的纪元纳秒(SystemTime 视角)。
pub fn now_nanos() -> DtNs {
    from_system_time(SystemTime::now())
}

/// 纪元纳秒所在交易日序数(向下取整,负纳秒同样正确)。
pub fn trading_day(t: DtNs) -> Day {
    t.div_euclid(NANOS_PER_DAY) as Day
}

/// `SystemTime` → 纪元纳秒(epoch 之前取负;独立函数,避免为基本类型
/// `i64` 实现外部 trait——orphan 规则)。
pub fn from_system_time(t: SystemTime) -> DtNs {
    match t.duration_since(UNIX_EPOCH) {
        Ok(d) => d.as_nanos() as DtNs,
        Err(e) => -(e.duration().as_nanos() as DtNs),
    }
}

/// `yyyy-mm-dd hh:mm:ss(.fffffffff 有 nanos 才显示)` 文本(UTC 视角)。
///
/// 仅供日志/调试;持久层自行格式化。
pub fn format_civil(t: DtNs) -> String {
    let c = civil_from_nanos(t);
    let base = format!(
        "{:04}-{:02}-{:02} {:02}:{:02}:{:02}",
        c.year, c.month, c.day, c.hour, c.minute, c.second
    );
    if c.nanos == 0 {
        base
    } else {
        format!("{base}.{:09}", c.nanos)
    }
}