Files
marqdo/lib/日期时间.mq.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

7.8 KiB
Executable File

markup, title, description
markup title description
occlusion lib/日期时间 日历时刻 map `{unix, zone, iso}`(中层 Mid2 M7)。固定偏移和内嵌 IANA 时区与夏令时规则。

日历时刻 map {unix, zone, iso}(中层 Mid2 M7)。固定偏移和内嵌 IANA 时区与夏令时规则。

处理时间戳、IANA 时区和当地日历。

能力与边界:zone 保留数值偏移,timezone 保留 IANA 身份。加按经过的秒数计算;加日历日保持当地钟点。夏令时缺口失败,重叠时间须明确选择策略。

本文件就是调用和开发手册:直接导入此文件,或用 marqdo call 按下面的函数标题调用。参数表说明类型和默认值;未填默认值的参数必须提供。返回表是渐进契约,后文说明失败与边界。

实现入口:src/host/datetime.rs、src/host/data_ops.rs

开发时保持中英文语义一致,先组合公开库;仅在 OS 或算法边界添加宿主原语并声明效应。修改后运行 marqdo check --narrative-ratio 本文件,并执行 tests/stdlib_tasks.rs 的真实任务。

现在

返回 类型 说明
result map 读取时钟并返回当前 UTC 日期时间记录

调用效应:time.read。

读取时钟并返回当前 UTC 日期时间记录。

完成后返回*读取时钟并返回当前 UTC 日期时间记录*。

自戳

参数 类型 默认 说明
秒 any 必填 以秒为单位的 Unix 时间戳
区 any None 本操作接受的固定偏移或命名时区
返回 类型 说明
result map 把 Unix 秒数转换为指定时区的日期时间记录;未指定时区时使用 UTC

这里使用秒、区=None。

调用效应:pure。

把 Unix 秒数转换为指定时区的日期时间记录;未指定时区时使用 UTC。

完成后返回*[把 Unix 秒数转换为指定时区的日期时间记录;未指定时区时使用 UTC](> host_datetime_from_unix unix=秒 zone=区)*。

成戳

参数 类型 默认 说明
时刻 any 必填 本库返回的日期时间记录,不是格式化文本
返回 类型 说明
result number 从日期时间记录读取 Unix 秒数;格式与时区表示不改变同一时刻

这里使用时刻。

调用效应:pure。

从日期时间记录读取 Unix 秒数;格式与时区表示不改变同一时刻。

完成后返回*[从日期时间记录读取 Unix 秒数;格式与时区表示不改变同一时刻](> host_datetime_to_unix dt=时刻)*。

解析

参数 类型 默认 说明
内容 any 必填 本操作读取、转换或输出的文本
格式 any None None 使用默认解析,或指定 rfc3339、strftime 格式
返回 类型 说明
result map 解析 RFC3339 或带可选时分秒的 YYYY-MM-DD 文本;显式格式使用 strftime 或 rfc3339

这里使用内容、格式=None。

调用效应:pure。

解析 RFC3339 或带可选时分秒的 YYYY-MM-DD 文本;显式格式使用 strftime 或 rfc3339。

完成后返回*[解析 RFC3339 或带可选时分秒的 YYYY-MM-DD 文本;显式格式使用 strftime 或 rfc3339](> host_datetime_parse text=内容 pattern=格式)*。

格式化

参数 类型 默认 说明
时刻 any 必填 本库返回的日期时间记录,不是格式化文本
样式 any None 宿主日期格式化接口接受的格式样式
返回 类型 说明
result text 把日期时间记录格式化为 rfc3339、date、time,或显式 strftime 格式的文本

这里使用时刻、样式=None。

调用效应:pure。

把日期时间记录格式化为 rfc3339、date、time,或显式 strftime 格式的文本。

完成后返回*[把日期时间记录格式化为 rfc3339、date、time,或显式 strftime 格式的文本](> host_datetime_format dt=时刻 style=样式)*。

加

参数 类型 默认 说明
时刻 any 必填 本库返回的日期时间记录,不是格式化文本
天 any None 增加的完整 24 小时时段数量
小时 any None 增加的小时数
分钟 any None 增加的分钟数
秒数 any None 增加的秒数
返回 类型 说明
result map 增加经过的天、小时、分钟与秒;这里一天固定为 24 小时,命名时区在移动后重新计算偏移

这里使用时刻、天=None、小时=None、分钟=None、秒数=None。

调用效应:pure。

增加经过的天、小时、分钟与秒;这里一天固定为 24 小时,命名时区在移动后重新计算偏移。

完成后返回*[增加经过的天、小时、分钟与秒;这里一天固定为 24 小时,命名时区在移动后重新计算偏移](> host_datetime_add dt=时刻 days=天 hours=小时 minutes=分钟 seconds=秒数)*。

时区

参数 类型 默认 说明
时刻 any 必填 本库返回的日期时间记录,不是格式化文本
区 any 必填 本操作接受的固定偏移或命名时区
返回 类型 说明
result map 用固定偏移或 IANA 时区重新表示同一时刻,保留其 Unix 时间戳

这里使用时刻、区。

调用效应:pure。

用固定偏移或 IANA 时区重新表示同一时刻,保留其 Unix 时间戳。

完成后返回*[用固定偏移或 IANA 时区重新表示同一时刻,保留其 Unix 时间戳](> host_datetime_in_zone dt=时刻 zone=区)*。

解析当地时间

参数 类型 默认 说明
内容 text 必填 本操作读取、转换或输出的文本
时区 text 必填 本操作接受的固定偏移或命名时区
歧义处理 text "reject" 夏令时重叠处理:reject、earliest 或 latest
返回 类型 说明
result map 解析 IANA 时区的当地时间并返回结果记录;夏令时缺口失败,重叠须选择 reject/earliest/latest。格式为年-月-日 时:分:秒。

这里使用内容、时区、歧义处理="reject"。

调用效应:pure。

直接调用此函数:

marqdo call lib/日期时间.mq.md 解析当地时间 '内容="2024-11-03 01:30:00"' '时区="America/New_York"' '歧义处理="earliest"' --effects none --json

解析 IANA 时区的当地时间并返回结果记录;夏令时缺口失败,重叠须选择 reject/earliest/latest。格式为年-月-日 时:分:秒。

完成后返回*[解析 IANA 时区的当地时间并返回结果记录;夏令时缺口失败,重叠须选择 reject/earliest/latest](> host_datetime_local text=内容 zone=时区 ambiguity=歧义处理)*。

加日历日

参数 类型 默认 说明
时刻 map 必填 本库返回的日期时间记录,不是格式化文本
天数 number 必填 增加的当地日历天数;跨夏令时保持墙钟时间
歧义处理 text "reject" 夏令时重叠处理:reject、earliest 或 latest
返回 类型 说明
result map 按当地日历增加日期并返回结果记录,跨夏令时保持当地钟点。旧 add 按持续秒数计算,一天为二十四小时。

这里使用时刻、天数、歧义处理="reject"。

调用效应:pure。

按当地日历增加日期并返回结果记录,跨夏令时保持当地钟点。旧 add 按持续秒数计算,一天为二十四小时。

完成后返回*[按当地日历增加日期并返回结果记录,跨夏令时保持当地钟点](> host_datetime_calendar_add dt=时刻 days=天数 ambiguity=歧义处理)*。