feat(stdlib): add datetime and project-mode clock APIs

This commit is contained in:
Marqdo Agent committed 2026-11-21 08:36:40 +08:00
1 parent cffb6790be
commit ae69391bc0
15 files changed
+527 -11

No files matched your search

+2
View File
@@ -15,6 +15,8 @@ module; a mismatch is a hard error.
- `data/json.mq.md` — recursive JSON parser and formatter (recoverable Result)
- `data/csv.mq.md` — quoted single-row CSV parser and formatter
- `data/table.mq.md` — value-returning table select/filter/sort/append/set/join/group/GFM
- `datetime.mq.md` — UTC ISO-8601 format/parse over Unix milliseconds (pure)
- `clock.mq.md` — project-mode `clock.now` over `resource.request`
- `path.mq.md` — lexical join/basename/dirname/extension/normalize (no I/O)
- `regex.mq.md` — `^ $ . * + ? [...]` matcher and search (no groups)
- `net/http.mq.md` — HTTP/1.1 response parsing (headers/chunked) and request builder
+8
View File
@@ -0,0 +1,8 @@
## 现在
`()`
返回项目模式下的 UTC Unix 毫秒。`pure`/`strict` 返回
`permission.denied`,与 `resource.request` 的其他操作一致。
*resource.request("clock.now", [])*
+299
View File
@@ -0,0 +1,299 @@
## 失败
`(消息)`
*{ok: false, code: "datetime.invalid", message: 消息}*
## 闰年
`(年)`
*年 % 4 == 0 and (年 % 100 != 0 or 年 % 400 == 0)*
## 每月天数
`(年, 月)`
1. `月 == 2`
1. `闰年(年)`
*29*
*28*
2. `月 == 4 or 月 == 6 or 月 == 9 or 月 == 11`
*30*
*31*
## 补零2
`(值)`
1. `值 < 10`
*"0" + 文本(值)*
*文本(值)*
## 补零3
`(值)`
1. `值 < 10`
*"00" + 文本(值)*
2. `值 < 100`
*"0" + 文本(值)*
*文本(值)*
## 补零4
`(值)`
1. `值 < 10`
*"000" + 文本(值)*
2. `值 < 100`
*"00" + 文本(值)*
3. `值 < 1000`
*"0" + 文本(值)*
*文本(值)*
## 月份
`(mp)`
1. `mp < 10`
*mp + 3*
*mp - 9*
## 年份
`(年, 月)`
1. `月 <= 2`
*年 + 1*
*年*
## 日期部件
`(天)`
Howard Hinnant 的 civil-from-days 算法,输入为 1970-01-01 起的天数。
**z = 天 + 719468**
**era = z // 146097**
**doe = z - era * 146097**
**yoe = (doe - doe // 1460 + doe // 36524 - doe // 146096) // 365**
**年 = yoe + era * 400**
**doy = doe - (365 * yoe + yoe // 4 - yoe // 100)**
**mp = (5 * doy + 2) // 153**
**日 = doy - (153 * mp + 2) // 5 + 1**
**月 = 月份(mp)**
*{年: 年份(年, 月), 月: 月, 日: 日}*
## 日期序号
`(年, 月, 日)`
**y = 年**
1. `月 <= 2`
**y = y - 1**
2. `true`
**忽略 = 0**
**era = y // 400**
**yoe = y - era * 400**
**m = 月**
1. `月 > 2`
**m = 月 - 3**
2. `true`
**m = 月 + 9**
**doy = (153 * m + 2) // 5 + 日 - 1**
**doe = yoe * 365 + yoe // 4 - yoe // 100 + doy**
*era * 146097 + doe - 719468*
## 是数字串
`(文本)`
**点 = text.codepoints(文本)**
**结果 = 长度(点) > 0**
**下标 = 0**
- `下标 < 长度(点) and 结果`
1. `点[下标] < 48 or 点[下标] > 57`
**结果 = false**
2. `true`
**忽略 = 0**
**下标 = 下标 + 1**
*结果*
## 片段
`(点, 起点, 终点)`
**结果 = ""**
**下标 = 起点**
- `下标 < 终点`
**结果 = 结果 + text.from_codepoint(点[下标])**
**下标 = 下标 + 1**
*结果*
## 格式化
`(毫秒)`
输出 UTC ISO-8601:`YYYY-MM-DDTHH:MM:SSZ`;毫秒非零时追加
`.mmm`。负数毫秒按 1970 前的 UTC 时间处理。
**秒 = 毫秒 // 1000**
**毫 = 毫秒 % 1000**
**天 = 秒 // 86400**
**日内 = 秒 % 86400**
**时 = 日内 // 3600**
**分 = 日内 % 3600 // 60**
**秒数 = 日内 % 60**
**日期 = 日期部件(天)**
**基 = 补零4(日期.年) + "-" + 补零2(日期.月) + "-" + 补零2(日期.日) + "T" + 补零2(时) + ":" + 补零2(分) + ":" + 补零2(秒数)**
1. `毫 == 0`
*基 + "Z"*
*基 + "." + 补零3(毫) + "Z"*
## 解析
`(文本)`
解析 `YYYY-MM-DDTHH:MM:SSZ` 或带 `.mmm` 的 UTC 文本,返回 Unix 毫秒。
范围、闰年和格式错误都是可恢复 `datetime.invalid`。
**点 = text.codepoints(文本)**
1. `长度(点) < 20 or 长度(点) > 24`
*失败("长度不是 20–24 个码点")*
1. `点[4] != 45 or 点[7] != 45 or 点[10] != 84 or 点[13] != 58 or 点[16] != 58`
*失败("分隔符不符合 YYYY-MM-DDTHH:MM:SS")*
**年文本 = 片段(点, 0, 4)**
**月文本 = 片段(点, 5, 7)**
**日文本 = 片段(点, 8, 10)**
**时文本 = 片段(点, 11, 13)**
**分文本 = 片段(点, 14, 16)**
**秒文本 = 片段(点, 17, 19)**
1. `not 是数字串(年文本) or not 是数字串(月文本) or not 是数字串(日文本) or not 是数字串(时文本) or not 是数字串(分文本) or not 是数字串(秒文本)`
*失败("日期时间分量必须是数字")*
**年 = 整数(年文本)**
**月 = 整数(月文本)**
**日 = 整数(日文本)**
**时 = 整数(时文本)**
**分 = 整数(分文本)**
**秒 = 整数(秒文本)**
**毫文本 = "0"**
**结束 = 20**
1. `长度(点) >= 24 and 点[19] == 46 and 点[23] == 90`
**毫文本 = 片段(点, 20, 23)**
**结束 = 24**
1. `长度(点) != 结束 or 点[结束 - 1] != 90`
*失败("必须以 Z 结尾")*
1. `not 是数字串(毫文本)`
*失败("毫秒必须是数字")*
**毫 = 整数(毫文本)**
1. `年 < 1970 or 月 < 1 or 月 > 12 or 日 < 1 or 日 > 每月天数(年, 月)`
*失败("日期超出范围")*
1. `时 < 0 or 时 > 23 or 分 < 0 or 分 > 59 or 秒 < 0 or 秒 > 59`
*失败("时间超出范围")*
**毫秒 = 日期序号(年, 月, 日) * 86400000 + 时 * 3600000 + 分 * 60000 + 秒 * 1000 + 毫**
*{ok: true, value: 毫秒}*
+1 -1
View File
@@ -1,5 +1,5 @@
{
"name": "marqdo-stdlib",
"version": "0.1.0",
"digest": "sha256:b692e264f046098b83c8046ae9c19ba03c116a078eaac3bdcf207d121e794ffb"
"digest": "sha256:030562dbce90a671f86fdef984620699925b39a302e2b68639ca752a94adde9c"
}
+10
View File
@@ -0,0 +1,10 @@
---
import:
clock: "std:clock"
---
## main
**现在 = clock.现在()**
*[现在.ok, 类型(现在.value), 现在.value > 1600000000000]*
+8
View File
@@ -0,0 +1,8 @@
---
import:
datetime: "std:datetime"
---
## main
*[datetime.格式化(0), datetime.格式化(1700000000123), datetime.解析("1970-01-01T00:00:00Z").value, datetime.解析("2026-11-21T08:00:00.123Z").value, datetime.解析("2026-13-01T00:00:00Z").ok, datetime.解析("2026-02-29T00:00:00Z").ok, datetime.格式化(-1)]*