Zig 时间、日期与时区处理：std.time 与 epoch 换算

test "wall clock" {
    const sec = std.time.timestamp();              // 例如 1791000000
    const ns = std.time.nanoTimestamp();           // i128
    try std.testing.expectEqual(@as(i64, 1_000_000), std.time.ns_per_ms);   // 用常量而非魔法数字
    _ = .{ sec, ns };
}

pub fn measure() !u64 {
    const start = try std.time.Instant.now();          // error.Unsupported 时无法单调计时
    // ... 被测代码 ...
    return start.since(try std.time.Instant.now());    // 纳秒差
}

pub fn bench(comptime f: anytype, args: anytype, iters: usize) u64 {
    for (0..50) |_| std.mem.doNotOptimizeAway(f(args));   // 预热
    var timer = std.time.Timer.start() catch unreachable;
    for (0..iters) |_| std.mem.doNotOptimizeAway(f(args));
    return timer.read() / iters;   // 平均纳秒
}

const std = @import("std");
const epoch = std.time.epoch;

pub const DateTime = struct {
    year: u16, month: u8, day: u8,        // month 1-12，day 1-31
    hour: u8, minute: u8, second: u8,
    weekday: u8,                          // 0 = 周日
};

/// 把 Unix 秒（UTC）分解为日历字段
pub fn toDateTime(unix_sec: i64) DateTime {
    const es = epoch.EpochSeconds{ .secs = @intCast(unix_sec) };
    const day_secs = es.getDaySeconds();
    const year_day = es.getEpochDay().calculateYearDay();
    const month_day = year_day.calculateMonthDay();
    return .{
        .year = year_day.year,
        .month = month_day.month.numeric(),
        .day = month_day.day_index + 1,       // day_index 从 0 开始
        .hour = day_secs.getHoursIntoDay(),
        .minute = day_secs.getMinutesIntoHour(),
        .second = day_secs.getSecondsIntoMinute(),
        .weekday = @intCast((es.secs / std.time.s_per_day + 4) % 7),   // 1970-01-01 是周四
    };
}

pub fn daysInMonth(year: u16, month: u8) u8 {
    const table = [_]u8{ 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 };
    if (month == 2 and epoch.isLeapYear(year)) return 29;   // 闰年二月
    return table[month - 1];
}

pub fn toUnixSeconds(dt: DateTime) i64 {
    var days: i64 = 0;
    var y: u16 = 1970;
    while (y < dt.year) : (y += 1) days += if (epoch.isLeapYear(y)) 366 else 365;
    var m: u8 = 1;
    while (m < dt.month) : (m += 1) days += daysInMonth(dt.year, m);
    days += dt.day - 1;
    return days * std.time.s_per_day + @as(i64, dt.hour) * 3600 + @as(i64, dt.minute) * 60 + dt.second;
}

const std = @import("std");

/// 输出 RFC 3339：2026-10-05T15:00:00Z
pub fn formatRfc3339(buf: []u8, dt: DateTime) ![]const u8 {
    return std.fmt.bufPrint(buf, "{d:0>4}-{d:0>2}-{d:0>2}T{d:0>2}:{d:0>2}:{d:0>2}Z", .{
        dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second,
    });
}

/// 带偏移：2026-10-05T23:00:00+08:00
pub fn formatWithOffset(buf: []u8, dt: DateTime, offset_min: i16) ![]const u8 {
    const sign: u8 = if (offset_min < 0) '-' else '+';
    const abs: u16 = @intCast(if (offset_min < 0) -offset_min else offset_min);
    return std.fmt.bufPrint(buf, "{d:0>4}-{d:0>2}-{d:0>2}T{d:0>2}:{d:0>2}:{d:0>2}{c}{d:0>2}:{d:0>2}", .{
        dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second, sign, abs / 60, abs % 60,
    });
}

pub fn parseRfc3339(s: []const u8) !i64 {
    if (s.len < 19) return error.TooShort;
    const year = try std.fmt.parseInt(u16, s[0..4], 10);
    const month = try std.fmt.parseInt(u8, s[5..7], 10);
    const day = try std.fmt.parseInt(u8, s[8..10], 10);
    const hour = try std.fmt.parseInt(u8, s[11..13], 10);
    const minute = try std.fmt.parseInt(u8, s[14..16], 10);
    const second = try std.fmt.parseInt(u8, s[17..19], 10);   // 无校验：生产代码需拒绝 month>12

    var offset_min: i32 = 0;
    if (s.len > 19 and s[19] != 'Z') {          // Z 表示 UTC，其余为 ±HH:MM
        if (s[19] != '+' and s[19] != '-') return error.BadFormat;
        const oh = try std.fmt.parseInt(i32, s[20..22], 10);
        const om = try std.fmt.parseInt(i32, s[23..25], 10);
        offset_min = oh * 60 + om;
        if (s[19] == '-') offset_min = -offset_min;
    }
    const local = toUnixSeconds(.{ .year = year, .month = month, .day = day,
        .hour = hour, .minute = minute, .second = second, .weekday = 0 });
    return local - offset_min * 60;   // 本地时间 → UTC 需要减去偏移
}

pub const Offset = struct {
    minutes: i16,   // 例如 +08:00 -> 480
    pub fn apply(self: Offset, utc_sec: i64) i64 { return utc_sec + @as(i64, self.minutes) * 60; }
    pub fn remove(self: Offset, local_sec: i64) i64 { return local_sec - @as(i64, self.minutes) * 60; }
};

const c = @cImport({
    @cInclude("time.h");
});

pub fn localParts(unix_sec: i64) ?DateTime {
    var t: c.time_t = @intCast(unix_sec);   // 32 位平台上 time_t 只有 32 位
    var tm: c.struct_tm = undefined;
    if (c.localtime_r(&t, &tm) == null) return null;   // localtime_r 是线程安全版本
    return .{
        .year = @intCast(tm.tm_year + 1900),   // tm_year 从 1900 起算
        .month = @intCast(tm.tm_mon + 1),      // tm_mon 从 0 起算
        .day = @intCast(tm.tm_mday), .hour = @intCast(tm.tm_hour),
        .minute = @intCast(tm.tm_min), .second = @intCast(tm.tm_sec), .weekday = @intCast(tm.tm_wday),
    };
}

/// 每 interval_ns 执行一次 tick，长时间运行不累积漂移
pub fn runLoop(interval_ns: u64, iterations: usize, tick: anytype) !void {
    var next = try std.time.Instant.now();
    for (0..iterations) |i| {
        tick(i);

        // 下一个截止时间 = 上一个截止时间 + 间隔（而不是 now + 间隔）
        const deadline = next.timestamp + interval_ns;
        const now = try std.time.Instant.now();
        if (deadline > now.timestamp) std.time.sleep(deadline - now.timestamp)
        else std.log.warn("loop behind by {d} ns", .{now.timestamp - deadline});  // 落后时不补跑
        next = .{ .timestamp = deadline };
    }
}

pub const TimeUtil = struct {
    pub fn nowUtc() DateTime {                 // 当前 UTC 日历时间
        return toDateTime(std.time.timestamp());
    }
    pub fn nowMs() i64 {                       // 当前时间戳（毫秒）
        return std.time.milliTimestamp();
    }
    pub fn rfc3339(buf: []u8) ![]const u8 {    // 格式化为 RFC 3339（UTC）
        return formatRfc3339(buf, nowUtc());
    }

    /// 把两个时间点之间的耗时格式化为人类可读
    pub fn humanDuration(ns: u64) struct { value: u64, unit: []const u8 } {
        if (ns >= std.time.ns_per_s) return .{ .value = ns / std.time.ns_per_s, .unit = "s" };
        if (ns >= std.time.ns_per_ms) return .{ .value = ns / std.time.ns_per_ms, .unit = "ms" };
        return .{ .value = ns / std.time.ns_per_us, .unit = "us" };
    }
};