time

表示与纪年

xtime 是有符号 int64，零点为公元 1 年 1 月 1 日 00:00:00.000 UTC。xtime == -1 是公元前 1 年 12 月 31 日 23:59:59.999。年份使用 … -2, -1, 1, 2 …，没有零年；负数的绝对值是公元前年份。日历按外推 Gregorian 规则计算，公元前 1 年对应天文纪年的零年。

全部毫秒值从 INT64_MIN 到 INT64_MAX 都能按 UTC 或固定偏移分解、原样重建，跨度约为零点前后各 2.92 亿年。UTC 偏移使用以东为正的秒数，范围为 -86399 到 86399。系统本地时区、文件系统和文本协议有各自的可表示范围；超出范围会报告错误。

xdatetime.Millisecond 的范围为 0 到 999；其余字段为 Year、Month、Day、Hour、Minute、Second、Offset、Weekday、YearDay、IsDST。星期日为 XTIME_SUNDAY == 0，年内日从 1 开始，IsDST 为 1、0 或未知值 -1。

计时与等待

Timer 使用平台高精度单调时钟。读数的原点没有日历意义，只用两次读数相减；系统日历校时不改变它。xrtTimer 读取失败返回 NaN 并报告错误。xrtNow 用于记录事件；它会受到系统日历校时影响。xrtSleep(0) 让出执行机会，负数睡眠参数无效。

Wait API 使用 int64 相对毫秒，XRT_WAIT_FOREVER == -1 表示无限等待，0 表示不阻塞，其余负值是参数错误。跨步骤共享预算由库内部处理。

Unix 双向转换

Unix 零点仍是 1970-01-01 UTC。秒转换对负绝对时间向负无穷取整：Unix 零点前 1 毫秒转成 Unix 秒是 -1。xrtTimeUnix 的结果对全部 xtime 都可表示；其余双向转换检查目标范围。失败不会修改调用方的输出，包括 Unix 32 位溢出和 Unix 毫秒减去纪元偏移后的溢出。

日期计算

xrtTimeAdd 以 xtimeunit 指定单位。毫秒、秒、分钟、小时、日、周是固定长度；月、季度、年按日历进位，月末钳制到目标月份末日，例如 2024-01-31 加一个月为 2024-02-29。跨公元前后会跳过不存在的零年。

xrtDateDiff(Start, End, Unit, &Result) 返回指定维度的 int64 差值，不生成浮点时长：

• 固定单位是经过的毫秒差除以对应单位，向零截断；23 小时差按日计算为 0。
• 月差按连续月份序号计算，2024-01-31 到 2024-02-01 为 1，反向为 -1。
• 年差按连续年份序号计算，公元前 1 年到公元 1 年为 1。
• 季度差为月差除以 3，向零截断。

单位枚举为 XTIME_UNIT_MILLISECOND、XTIME_UNIT_SECOND、XTIME_UNIT_MINUTE、XTIME_UNIT_HOUR、XTIME_UNIT_DAY、XTIME_UNIT_WEEK、XTIME_UNIT_MONTH、XTIME_UNIT_QUARTER、XTIME_UNIT_YEAR。

计算检查最终结果，避免中间乘法溢出错误拒绝可表示结果。两端毫秒差可能超出 int64；此时 xrtDateDiff 返回 false，输出保持原值。原始 End - Start 只有在差值可表示时才能直接使用 C 有符号减法。

xrtTimePart 返回日内毫秒；xrtDatePart 返回当日 UTC 零点。极端时间的零点可能不可表示，此时后者返回 0 并报告 XTIME_ERROR_OVERFLOW。月、年、周区间是 [Start, End)；ISO 周编号使用星期一为 1、星期日为 7。

本地时区与文本

time_local 根据操作系统历史时区规则转换。DST gap 报告 XTIME_ERROR_LOCAL_GAP；fold 通过 XTIME_FOLD_REJECT、XTIME_FOLD_EARLIER、XTIME_FOLD_LATER 明确选择。固定偏移转换不猜测 DST。

time_text 的 %f 写入或解析三位毫秒。RFC 3339 可以接受更多小数位，丢弃毫秒以下尾数，写入时删除小数尾零；协议中的四位年份 0000 映射到公元前 1 年。HTTP-date 使用 GMT 和秒精度，支持正公元四位年份。通用格式按公元纪年拒绝零年。xrtTimeTryParseHTTPDate 失败时同时保留输出和已有线程错误。

格式化支持 %Y %y %m %d %e %H %I %M %S %f %p %P %a %A %b %B %w %j %q %z %F %T %R %% 和支持的无填充数字字段，例如 %-m。缓冲写入返回所需长度；拥有型字符串由 xrtFree 释放。

完整函数声明

以下声明以 time.h 为准。

星期枚举按 XTIME_SUNDAY、XTIME_MONDAY、XTIME_TUESDAY、XTIME_WEDNESDAY、XTIME_THURSDAY、XTIME_FRIDAY、XTIME_SATURDAY 排列，取值 0 至 6。