企业官网建设流程全解析

• 文档
• 知识库
• 教程
• OpenHarmony

std.time是仓颉编程语言标准库中负责时间处理的包，提供了日期时间（DateTime）、单调时间（MonoTime）、时区（TimeZone）以及星期（DayOfWeek）、月份（Month）等核心类型，并内置了一套功能完备的时间字符串解析与格式化规则。本文以仓库中的 time 包总览文档 为主体，结合 time 包 API 文档 与各示例文档，系统讲解std.time的类型体系、格式化字母规则、常用 API 与实战用法。读完本文，你将掌握时间字符串的解析/格式化规范、时区的加载与自定义方式，并能独立使用DateTime与MonoTime完成日期运算、跨时区比较与高精度计时。

一、std.time 包概览

time包提供了与时间相关的类型，包括日期时间、时间间隔、单调时间和时区等，并提供了计算和比较的功能。它属于std标准库的一部分，在 std 模块总览 中被定位为"提供与时间相关的类型……并提供了计算和比较的功能"。

从源码结构看，std.time的类型体系由以下几类组成（API 文档位于 libs/std/time/time_package_api/）：

其中DateTime与MonoTime都依赖 core 包中的Duration类型（定义见 core 包结构体文档）来表达时间间隔。

二、时间字符串格式：解析约束与字母规则

DateTime的字符串解析与格式化都遵循一套统一的格式规则，这套规则是std.time包的核心。在使用DateTime.parse(str, format)、DateTime.format(fmt)以及DateTimeFormat时都必须遵循。

2.1 字符串解析的四大要求

使用字符串解析时间时，有以下硬性要求：

1. 必须包含年月日信息：字符串必须包含描述具体年月日的信息，如公元年（y）+ 月（M）和日（d），或公元年（y）和一年中的第几天（D）。
2. 缺失字段自动取默认值：如果不包含时分秒的描述信息，则均默认为 0；如果不包含时区信息，则默认为当前时区TimeZone.Local。
3. 同一字母不允许重复取值：对同一字母表示的格式不允许两次取值，如不允许两次对公元年（y）格式的赋值；表示时区的O和Z两种格式同样不允许一起出现。
4. 部分字母作为辅助验证信息：其余的部分字母格式会作为辅助信息验证。例如"2023-04-24-Mon"使用格式"yyyy-MM-dd-www"解析时，会验证"Mon"的正确性。

2.2 字母含义表

格式字符串中的每个字母都有特定含义，规则如下：

字母的重复次数（即连续书写的数量）决定了该字段的解析宽度与输出宽度，各字母的详细规则见下文各小节。

2.3 上下午（a）

合法个数为 1，表示上午或者下午，固定为"AM"或"PM"。

2.4 年（y / Y）

注意y（公元年）与Y（基于周的年）的区别：y表示普通的公历年份，而Y表示基于 ISO 周历的年，常与W（ISO-8601 周）配合使用。

2.5 月（M）

2.6 数值（h / H / m / s 等）

不同 number 类型数据的表示范围根据实际值大小变动：

2.7 小数秒（S）

2.8 时区偏移量（O）

2.9 时区名和时区 ID（z）

2.10 距零时区偏移（Z）

2.11 以年算的天数（D）

2.12 以周算的天（w）

2.13 纪年（G）

三、DateTimeFormat：内置 RFC 标准时间格式

DateTimeFormat类（API 文档）提供时间格式的功能，用于解析和生成DateTime。它内置了四个符合 RFC 标准的时间格式常量：

注意：DateTimeFormat的format属性和of(String)工厂方法在当前版本中标记为deprecated（未来版本即将废弃），官方推荐直接使用DateTime.format(fmt: String)与DateTime.parse(str: String, format: String)这类接受字符串格式的 API 替代。

四、TimeZone：时区的加载、自定义与比较

TimeZone类（API 文档）表示时区，记录了某一地区在不同时间较零时区的时间偏移，实现了ToString与Equatable<TimeZone>接口。

4.1 预置时区：Local 与 UTC

• TimeZone.Local：本地时区。其行为与load()相同：从系统环境变量TZ中获取时区 ID（标准格式如"Asia/Shanghai"），再据该 ID 从系统时区文件加载时区。若TZ未设置或为空：
  • 在 Linux/Unix-like 系统上，加载系统路径/etc/localtime链接，时区名与/etc/localtime指向的相对路径名相同（如Asia/Shanghai）；
  • 若上一步失败或在 Windows 系统上，返回 ID 为"UTC&偏移量"的时区（如Asia/Shanghai对应的时区为"UTC+08:00"）。
• TimeZone.UTC：UTC 时区，即零时区。

4.2 从系统加载时区：load / loadFromPaths / loadFromTZData

• static func load(id: String): TimeZone：从系统中加载id指定的时区。不同平台的加载路径规则不同（详见 API 文档）：
  • Linux、macOS、HarmonyOS：若存在环境变量CJ_TZPATH，则按该变量指定的路径加载时区文件（多个路径以:分隔，按先后顺序查找并加载第一个找到的时区文件）；否则从系统时区文件目录加载（Linux 和 macOS 为/usr/share/zoneinfo，HarmonyOS 不支持该默认目录）。
  • Windows：需自行下载 IANA 时区数据并编译，设置环境变量CJ_TZPATH指向 zoneinfo 目录（多个路径以;分隔），否则会导致异常。
  • 异常：id为空、长度超过 4096 字节或不符合标准时区 ID 格式时抛IllegalArgumentException；时区文件加载失败（找不到文件、解析失败等）时抛InvalidDataException。
• static func loadFromPaths(id: String, tzpaths: Array<String>): TimeZone：根据tzpaths指定的时区文件目录加载时区，从第一个读取成功的时区文件路径中加载；时区文件格式需满足 RFC 8536（时区信息格式）。
• static func loadFromTZData(id: String, data: Array<UInt8>): TimeZone：使用指定的时区 ID 和 IANA 时区文件格式的数据构造自定义TimeZone。id可以是任何合法字符串，data解析失败时抛InvalidDataException。

4.3 自定义时区与基础能力

• init(id: String, offset: Duration)：使用指定的时区 ID 和偏移量构造自定义TimeZone。id使用/作为分隔符（如"Asia/Shanghai"）；offset是相对 UTC 时区的偏移量，精度为秒，向东为正、向西为负，取值范围为(-25 * Duration.hour, 26 * Duration.hour)。id为空字符串或offset超出有效区间时抛IllegalArgumentException。
• prop id: String：获取当前实例关联的时区 ID。
• func toString(): String：返回时区 ID 的字符串表示。
• operator ==/!=：按引用判断两个TimeZone是否相等。

五、DateTime：日期时间的构造、读取与运算

DateTime结构体（API 文档）表示日期时间，是一个描述某一时间点的时间类型，实现了ToString、Hashable、Comparable<DateTime>、Formattable与Parsable<DateTime>接口。

5.1 不可变性与底层时钟

• DateTime是不可变类型，包含日期、时间和时区信息。可表示的时间区间为[-999,999,999-01-01T00:00:00.000000000, 999,999,999-12-31T23:59:59.999999999]，该区间适用于任何合法时区。
• now()与nowUTC()获取当前时间使用的系统调用为clock_gettime（CLOCK_REALTIME），在 Linux、Windows、macOS 上一致。由于受系统时间影响，需要不受系统时间影响的计时场景应改用MonoTime。

5.2 构造方式

DateTime提供了多种静态构造方法：

参数校验规则：年范围[-999,999,999, 999,999,999]，月范围[1, 12]，日范围[1, 31]（最大值需与月份匹配，可能是 28、29、30、31），时[0, 23]，分/秒[0, 59]，纳秒[0, 999,999,999]；超范围抛IllegalArgumentException。UnixEpoch即零时区1970年1月1日0时0分0秒0纳秒。

5.3 属性读取

DateTime提供了丰富的只读属性，示例见 datetime_prop 示例：

• 日期相关：year、month（Month类型）、monthValue（deprecated，数字形式）、dayOfMonth、dayOfYear、dayOfWeek（DayOfWeek类型）、date（返回(Int64, Month, Int64)元组）、isoWeek（返回基于 ISO8601 标准的(年, 周数)元组）
• 时间相关：hour、minute、second、nanosecond、time（返回(时, 分, 秒)元组）
• 时区相关：zone（TimeZone）、zoneId（String）、zoneOffset（Duration）

在 datetime_prop 示例 中，对2024-05-22T12:34:56.789+08:00读取各属性，输出为：

datetime is 2024, May, 22, 12, 34, 56, 789000000, Asia/Shanghai, 8h datetime.toString() = 2024-05-22T12:34:56.789+08:00 Wednesday, 143th day, 21th week of 2024

5.4 日期时间计算

DateTime支持多种加法运算，均返回新的DateTime实例（不可变）：

• addYears(n)、addMonths(n)、addWeeks(n)、addDays(n)、addHours(n)、addMinutes(n)、addSeconds(n)、addNanoseconds(n)。
• 运算符：DateTime + Duration、DateTime - Duration、DateTime - DateTime（返回Duration）。

需要注意月和年的长度不固定，API 文档明确给出了两个典型语义：

• addMonths：设dt表示2020年3月31日，dt.addMonths(1)不会返回非法日期2020年4月31日，而是偏移到当月最后一天，返回2020年4月30日。
• addYears：设dt表示2020年2月29日，dt.addYears(1)不会返回非法日期2021年2月29日，而是偏移到当月最后一天，返回2021年2月28日。

结果超出表示范围时抛ArithmeticException。

5.5 解析与格式化（与时间字符串格式规则配合）

• static func parse(str: String): DateTime：按RFC3339的date-time格式解析，可包含小数秒，如"2023-04-10T08:00:00[.123456]+08:00"（[]为可选项）；解析失败抛TimeParseException。
• static func parse(str: String, format: String): DateTime：按format指定的格式解析，例如"2023/04/10 08:00:00 +08:00"配合"yyyy/MM/dd HH:mm:ss OOOO"。同一format多次取值或无法解析时抛TimeParseException；format格式不正确时抛IllegalArgumentException。
• static func tryParse(str: String): Option<DateTime>：尝试解析，失败时返回Option.None，适合不希望抛出异常的防御性场景。
• func format(fmt: String): String：按fmt生成字符串，例如"yyyy/MM/dd HH:mm:ss OOOO"。
• func toString(): String：返回RFC3339的date-time格式字符串，若包含非零纳秒信息则打印小数秒。

datetime_parse 示例 完整演示了格式化与解析的闭环：

import std.time.* main() { let pattern = "yyyy/MM/dd HH:mm:ssSSS OO" let datetime = DateTime.of( year: 2024, month: May, dayOfMonth: 22, hour: 12, minute: 34, second: 56, nanosecond: 789000000, timeZone: TimeZone.load("Asia/Shanghai") ) let str = datetime.format(pattern) println(str) println(DateTime.parse(str, pattern)) }

运行结果：

2024/05/22 12:34:56789000000 +08:00 2024-05-22T12:34:56.789+08:00

这里SSS将纳秒789000000格式化为 9 位小数秒789000000，体现了"小数秒字母数量决定位数"的规则。

5.6 跨时区比较与转换

DateTime的比较基于UTC 时间：指向更早 UTC 时间的DateTime更小。支持compare(rhs)（返回Ordering.GT/EQ/LT）、运算符==、!=、<、<=、>、>=，以及hashCode()。两个DateTime相等意味着它们指向同一 UTC 时间。

datetime_compare 示例 选取上海（Asia/Shanghai）与纽约（America/New_York）两个时区进行比较：

import std.time.* main() { let tzSH = TimeZone.load("Asia/Shanghai") let tzNY = TimeZone.load("America/New_York") // 2024-05-25T00:00:00Z let shanghai1 = DateTime.of(year: 2024, month: May, dayOfMonth: 25, hour: 8, timeZone: tzSH) let new_york1 = DateTime.of(year: 2024, month: May, dayOfMonth: 24, hour: 20, timeZone: tzNY) // 2024-05-25T01:00:00Z let shanghai2 = DateTime.of(year: 2024, month: May, dayOfMonth: 25, hour: 9, timeZone: tzSH) let new_york2 = DateTime.of(year: 2024, month: May, dayOfMonth: 24, hour: 21, timeZone: tzNY) println(shanghai1 == new_york1) // true，同一 UTC 时间 println(shanghai1 != new_york2) // true println(shanghai1 <= new_york2) // true println(shanghai1 < new_york2) // true println(shanghai2 >= new_york1) // true println(shanghai2 > new_york1) // true }

时区转换使用inLocal()、inUTC()、inTimeZone(timeZone)，datetime_tz 示例 演示了同一时刻在三个时区的本地时间：

CST: 2024-05-22T12:00:00+08:00 UTC: 2024-05-22T04:00:00Z EDT: 2024-05-22T00:00:00-04:00

5.7 Unix 时间戳互转

• toUnixTimeStamp(): Duration：获取当前实例自UnixEpoch的时间间隔。
• fromUnixTimeStamp(d: Duration)与ofEpoch(second, nanosecond)：从 Unix 时间戳反推日期时间，结果超范围时抛ArithmeticException。

六、MonoTime：不受系统时间影响的单调计时

MonoTime结构体（API 文档）表示单调时间，是一个用来衡量经过时间的时间类型，类似于一直运行的秒表，实现了Hashable与Comparable<MonoTime>。

6.1 核心特性

• 可表示范围为[Duration.Zero, Duration.Max]，数值表示为[0, 2^63)（单位为秒），精度为纳秒。
• 通过now()创建的MonoTime总是晚于先前用该方法创建的MonoTime，因此不受系统时间调整影响，常用于性能测试和时间优先的任务队列。
• 底层系统调用为clock_gettime（CLOCK_MONOTONIC），在 Linux、Windows、macOS 上一致。

6.2 常用 API

• static func now(): MonoTime：获取与当前时间对应的单调时间。
• 计算：MonoTime + Duration、MonoTime - Duration、MonoTime - MonoTime（返回Duration，即经过的时间间隔）。
• 比较：compare(rhs)、==、!=、<、<=、>、>=，以及hashCode()。

monotime_test 示例 演示了典型的耗时统计写法：

import std.time.* const count = 10000 main() { let start = MonoTime.now() for (_ in 0..count) { DateTime.now() } let end = MonoTime.now() let result = end - start println("total cost: ${result.toNanoseconds()}ns") }

运行结果（以实际运行为准）：

total cost: 951159ns

MonoTime也常与std.sync包的Timer配合使用，例如在 sync 包 Timer 示例 中，用MonoTime.now() - start测量定时任务触发时距起点的时间：

import std.time.MonoTime main() { let start = MonoTime.now() Timer.once(Duration.second, {=> println("Tick at: ${MonoTime.now() - start}") }) sleep(Duration.second * 2) 0 }

七、DayOfWeek 与 Month 枚举

7.1 DayOfWeek

DayOfWeek（API 文档）表示一周中的某一天，取值包括Sunday、Monday、Tuesday、Wednesday、Thursday、Friday、Saturday，实现了ToString与Equatable<DayOfWeek>。

• static func of(dayOfWeek: Int64): DayOfWeek：整数转枚举，合法范围[0, 6]，0 表示周日，1 至 6 表示周一至周六；越界抛IllegalArgumentException。
• toInteger(): Int64：枚举转整数（周日为 0，周一至周六为 1 至 6）。value()为 deprecated 版本，推荐使用toInteger()。
• toString(): String：返回如"Monday"的字符串。
• 运算：==、!=；DayOfWeek + n/DayOfWeek - n可计算n天之后/之前（n为正数时）的星期值，n为负数则方向相反。

7.2 Month

Month（API 文档）用以表示月份，取值包括January至December，实现了ToString与Equatable<Month>。

• static func of(mon: Int64): Month：整数转枚举，合法范围[1, 12]；越界抛IllegalArgumentException。
• toInteger(): Int64：枚举转整数（一月为 1，十二月为 12）。value()为 deprecated 版本，推荐使用toInteger()。
• toString(): String：返回如"January"的字符串。
• 运算：==、!=；Month + n/Month - n可计算n个月之后/之前（n为正数时）的日历月份，n为负数则方向相反。

八、异常体系

std.time定义了两个专属异常类（API 文档），均继承自 core 包的Exception，支持无参构造和带消息构造：

• InvalidDataException：表示加载时区时的异常。当TimeZone.load、loadFromPaths、loadFromTZData找不到时区文件或时区文件解析失败时抛出。
• TimeParseException：表示解析时间字符串时的异常。当DateTime.parse无法正常解析，或同一format存在多次取值时抛出。

此外，API 文档中还常涉及 core 包的两个异常：参数越界时抛IllegalArgumentException（如构造DateTime.of参数超范围、TimeZone构造参数非法、format格式不正确）；计算溢出时抛ArithmeticException（如addDays、DateTime + Duration结果超出表示范围）。

九、实战要点小结

1. 格式字符串是"解析+输出"的双向协议：字母及其数量同时决定了解析宽度与输出宽度，且对同一字母不允许重复取值，O与Z不允许同时出现；w、G等字母会作为辅助校验信息参与解析验证。
2. 默认值规则：字符串缺少时分秒则默认 0，缺少时区则默认TimeZone.Local；构造DateTime.of时hour/minute/second/nanosecond均默认 0，时区默认TimeZone.Local。
3. 时间比较看 UTC：DateTime的大小与相等比较基于 UTC 时间，跨时区实例可直接用==/<等运算符比较；换时区展示用inTimeZone()/inUTC()/inLocal()。
4. 计时优先MonoTime：需要不受系统时间影响的耗时统计（性能测试、定时器间隔）时使用MonoTime，DateTime.now()受系统时间调整影响。
5. 时区加载跨平台注意：Linux/macOS 依赖系统 zoneinfo 或CJ_TZPATH，Windows 需自行下载 IANA 时区数据并设置CJ_TZPATH，否则TimeZone.load会抛异常。

以上内容覆盖了 time 包总览文档 的全部核心规则与类型清单。若需查阅更细粒度的 API 签名与示例，可继续阅读 time 包 API 目录 中的类、结构体、枚举与异常文档，以及 time 包示例目录 下的 5 个实战示例（解析格式化、属性读取、跨时区比较、时区转换、MonoTime 计时）。

• 文档
• 知识库
• 教程
• OpenHarmony