#TZif Engine

#功能范围

• 解析 TZif v2/v3 的双数据块、transition、time type、designation、leap record、 ttisstd / ttisut 指示器和 POSIX TZ footer；
• 校验 header 计数、数据长度、transition 顺序、UTC offset、leap record、指示器和 footer 一致性，并对输入规模设置解析上限；
• 支持 UTC → 本地时间，以及本地时间的 unique、gap、overlap 判定；
• 对 overlap 提供全部 UTC 候选或 PreferEarlier / PreferLater 选择策略；
• 使用 Int64 处理时间戳，支持历史秒级偏移和 2038 年之后的转换；
• 解析 POSIX TZ 的 J<n>、n、M<m>.<w>.<d> 规则与 wall、standard、UTC 时钟基准，用于显式 transition 范围外的外推；
• 提供 ISO-8601 解析与格式化、活动 offset 来源、transition 明细和区间查询；
• 提供十六进制 TZif 输入的命令行工具，便于在不引入文件系统依赖的情况下检查数据。

#快速开始

moon run examples --target native

1970-01-01T00:00:00Z becomes 1970-01-01T08:00:00+08:00 CST
embedded America/New_York: 2026-03-08T03:00:00-04:00 EDT

TZIF_HEX=$(xxd -p /usr/share/zoneinfo/America/New_York | tr -d '\n')
moon run cli --target native -- utc-to-local "$TZIF_HEX" 1772953200

2026-03-08T03:00:00-04:00 EDT

#库 API

import {
  "caijiewei295/tzif-engine" @tzif,
  "caijiewei295/tzif-engine/types",
}

fn convert(
  tzif_bytes : Bytes,
  utc_time : Int64,
) -> Result[@types.LocalDateTime, @types.TzifError] {
  let timezone = match @tzif.load(tzif_bytes) {
    Ok(value) => value
    Err(error) => return Err(error)
  }
  @tzif.utc_to_local(timezone, utc_time)
}

fn choose_later_overlap(
  timezone : @types.TzifData,
) -> Result[Int64, @types.TzifError] {
  let local_time = match @tzif.parse_iso_local("2026-11-01T01:30:00") {
    Ok(value) => value
    Err(error) => return Err(error)
  }
  @tzif.local_to_utc(timezone, local_time, @types.PreferLater)
}

#嵌入时区数据

#验证

moon fmt --check
moon check --target all --warn-list +73 --deny-warn
moon build --target all --warn-list +73 --deny-warn
moon test --target all --warn-list +73 --deny-warn
moon info --target all

#设计边界

• 只解析 TZif v2/v3；不提供时区名称到文件路径的查找；
• 不下载或自动更新 IANA 时区数据库，文件读取和输入大小策略由宿主负责；
• leap record 会被保留和校验，但不参与 POSIX civil-time 计算；
• 不提供本地化时区名称；
• ISO-8601 文本接口限定四位年份和可互操作的 numeric offset，底层 TZif reader 仍接受 RFC 9636 允许的更宽 offset 范围；
• 仓库中的 America/New_York 仅用于示例、测试和基准，不是完整 tzdb 分发。

#文档

• 架构设计
• 项目申报书

#许可证