time 包

介绍

time 包提供了时间操作相关的能力，包括时间的读取、时间计算、基于时区的时间转换、时间的序列化和反序列化等功能。

主要接口

struct Duration

public struct Duration <: ToString & Hashable & Comparable<Duration>

Duration 用以表示一段时间间隔，其精度为纳秒，可表示范围为 Duration.Min 至 Duration.Max，数值表示为[-2⁶³, 2⁶³)（单位为秒）。提供了一些常用时间间隔的静态成员实例、时间间隔的计算以及比较函数等。

Duration 中的规则：

每个时间单位（小时、分、秒等）均用整数表示，如果实际值不为整数，则向绝对值小的方向取整，向绝对值小的方向取整：例如，2.8 小时取整为 2小时，-2.8 小时取整为 -2小时，0.5 分钟取整为 0 分钟，-0.7 秒取整为 0 秒。

Duration 提供的 API 如下所示：

prop Max

public static prop Max: Duration

功能：表示最大时间间隔的 Duration 实例，其值为 “9223372036854775807秒999999999纳秒”。

prop Min

public static prop Min: Duration

功能：表示最小时间间隔的 Duration 实例，其值为 “-9223372036854775807秒”。

func since

public static func since(t: DateTime): Duration

功能：计算从参数 t 开始到当前时间为止的时间间隔。

参数：

t：DateTime 实例

返回值：Duration 实例

func until

public static func until(t: DateTime): Duration

功能：计算从当前时间开始到参数 t 为止的时间间隔。

参数：

t：DateTime 实例

返回值：Duration 实例

func toDays

public func toDays(): Int64

功能：获得当前 Duration 实例以“天”为单位的整数大小，向绝对值小的方向取整。

返回值：当前 Duration 实例以“天”为单位的大小

func toHours

public func toHours(): Int64

功能：获得当前 Duration 实例以“小时”为单位的整数大小，向绝对值小的方向取整。

返回值：当前 Duration 实例以“小时”为单位的大小

func toMinutes

public func toMinutes(): Int64

功能：获得当前 Duration 实例以“分钟”为单位的整数大小，向绝对值小的方向取整。

返回值：当前 Duration 实例以“分钟”为单位的大小

func toSeconds

public func toSeconds(): Int64

功能：获得当前 Duration 实例以“秒”为单位的整数大小，向绝对值小的方向取整。

返回值：当前 Duration 实例以“秒”为单位的大小

func toMilliseconds

public func toMilliseconds(): Int64

功能：获得当前 Duration 实例以“毫秒”为单位的整数大小，向绝对值小的方向取整。

返回值：当前 Duration 实例以“毫秒”为单位的大小

异常：

ArithmeticException：当 Duration 实例以“毫秒”为单位的大小超过 Int64 表示范围时，抛出异常。

func toMicroseconds

public func toMicroseconds(): Int64

功能：获得当前 Duration 实例以“微秒”为单位的整数大小，向绝对值小的方向取整。

返回值：当前 Duration 实例以“微秒”为单位的大小

异常：

ArithmeticException：当 Duration 实例以“微秒”为单位的大小超过 Int64 表示范围时，抛出异常。

func toNanoseconds

public func toNanoseconds(): Int64

功能：获得当前 Duration 实例以“纳秒”为单位的整数大小，向绝对值小的方向取整。

返回值：当前 Duration 实例以“纳秒”为单位的大小

异常：

ArithmeticException：当 Duration 实例以“纳秒”为单位的大小超过 Int64 表示范围时，抛出异常。

func toString

public func toString(): String

功能：获得当前 Duration 实例的字符串表示，格式形如："1d2h3m4s5ms6us7ns"，表示“1天2小时3分钟4秒5毫秒6微秒7纳秒”。某个单位下数值为 0 时此项会被省略，特别地，当所有单位下数值都为 0 时，返回 "0s"。

返回值：当前 Duration 实例的字符串表示

func hashCode

public func hashCode(): Int64

功能：获得当前 Duration 实例的哈希值。

返回值：当前 Duration 实例的哈希值

func abs

public func abs(): Duration

功能：返回一个新的 Duration 实例，其值大小为当前 Duration 实例绝对值。

返回值：当前 Duration 实例取绝对值的结果

异常：

ArithmeticException：如果当前 Duration 实例等于 Duration.Min，会因为取绝对值超出 Duration 表示范围而抛异常

operator func +

public operator func +(r: Duration): Duration

功能：重载操作符 +，实现 "Duration + Duration = Duration"，返回新的 Duration 实例表示和。

参数：

r：Duration 实例，加法的右操作数

返回值：加法运算的结果

异常：

ArithmeticException：当相加后的结果超出 Duration 的表示范围时，抛出异常

operator func -

public operator func -(r: Duration): Duration

功能：重载操作符 -，实现 "Duration - Duration = Duration"，返回新的 Duration 实例表示差。

参数：

r：Duration 实例，减法的右操作数

返回值：减法运算的结果

异常：

ArithmeticException：当相减后的结果超出 Duration 的表示范围时，抛出异常

operator func *

public operator func *(r: Int64): Duration

功能：重载操作符 *，实现 "Duration * Int64 = Duration"，返回新的 Duration 实例表示积。

参数：

r：Int64 类型，乘法的右操作数

返回值：乘法运算的结果

异常：

ArithmeticException：当相乘后的结果超出 Duration 的表示范围时，抛出异常

operator func *

public operator func *(r: Float64): Duration

功能：重载操作符 *，实现 "Duration * Float64 = Duration"，返回新的 Duration 实例表示积。由于 Float64 的精度受限，当 Duration 超过一定范围时，结果会不准确。

参数：

r：Float64 类型，乘法的右操作数

返回值：乘法运算的结果，最小精度为纳秒，不足一纳秒部分向绝对值小的方向取整

异常：

ArithmeticException：当相乘后的结果超出 Duration 的表示范围时，抛出异常

operator func /

public operator func /(r: Int64): Duration

功能：重载操作符 /，实现 "Duration / Int64 = Duration"，返回新的 Duration 实例表示商。

参数：

r：Int64 类型，除法的右操作数

返回值：除法运算的结果

异常：

IllegalArgumentException：当 r 等于 0 时，抛出异常
ArithmeticException：当相除后的结果超出 Duration 的表示范围时，抛出异常

operator func /

public operator func /(r: Float64): Duration

功能：重载操作符 /，实现 "Duration / Float64 = Duration"，返回新的 Duration 实例表示商。由于 Float64 的精度受限，当 Duration 超过一定范围时，结果会不准确。

参数：

r：Float64 类型，除法的右操作数

返回值：除法运算的结果

异常：

IllegalArgumentException：当 r 等于 0 时，抛出异常
ArithmeticException：当相除后的结果超出 Duration 的表示范围时，抛出异常

operator func /

public operator func /(r: Duration): Float64

功能：重载操作符 /，实现 "Duration / Duration = Float64"，返回一个浮点数表示商。

参数：

r：Duration 实例，除法的右操作数

返回值：除法运算的结果

异常：

IllegalArgumentException：当 r 等于 Duration.Zero 时，抛出异常

operator func ==

public operator func ==(r: Duration): Bool

功能：重载操作符 ==，实现 "Duration == Duration" 的判断，返回当前 Duration 实例是否等于 r。

参数：

r：Duration 实例，== 运算的右操作数

返回值：当前 Duration 实例是否等于 r

operator func !=

public operator func !=(r: Duration): Bool

功能：重载操作符 !=，实现 "Duration != Duration" 的判断，返回当前 Duration 实例是否不等于 r。

参数：

r：Duration 实例，!= 运算的右操作数

返回值：当前 Duration 实例是否不等于 r

operator func >=

public operator func >=(r: Duration): Bool

功能：重载操作符 >=，实现 "Duration >= Duration" 的判断，返回当前 Duration 实例是否大于等于 r。

参数：

r：Duration 实例，>= 运算的右操作数

返回值：当前 Duration 实例是否大于等于 r

operator func >

public operator func >(r: Duration): Bool

功能：重载操作符 >，实现 "Duration > Duration" 的判断，返回当前 Duration 实例是否大于 r。

参数：

r：Duration 实例，> 运算的右操作数

返回值：当前 Duration 实例是否大于 r

operator func <=

public operator func <=(r: Duration): Bool

功能：重载操作符 <=，实现 "Duration <= Duration" 的判断，返回当前 Duration 实例是否小于等于 r。

参数：

r：Duration 实例，<= 运算的右操作数

返回值：当前 Duration 实例是否小于等于 r

operator func <

public operator func <(r: Duration): Bool

功能：重载操作符 <，实现 "Duration < Duration" 的判断，返回当前 Duration 实例是否小于 r。

参数：

r：Duration 实例，< 运算的右操作数

返回值：当前 Duration 实例是否小于 r

func compare

public func compare(rhs: Duration): Ordering

功能：比较当前 Duration 实例与另一个 Duration 实例的关系，如果大于，返回 Ordering.GT；如果等于，返回 Ordering.EQ；如果小于，返回 Ordering.LT。

参数：

rhs：参与比较的 Duration 实例

返回值：当前 Duration 实例与 rhs 的大小关系

interface DurationExtension

public interface DurationExtension {
    operator func *(r: Duration): Duration
}

DurationExtension 用于拓展 Duration 实例作为右操作数时，返回积为新 Duration 实例的乘法运算。

operator func *

operator func *(r: Duration): Duration

功能：重载操作符 *，实现 "T * Duration = Duration"，返回新的 Duration 实例表示积。

参数：

r：Duration 实例，乘法的右操作数

返回值：乘法运算的结果

异常：

ArithmeticException：当相乘后的结果超出 Duration 的表示范围时，抛出异常

extend Int64 <: DurationExtension

extend Int64 <: DurationExtension

拓展了 Int64 类型作为左操作数和 Duration 类型作为右操作数的乘法运算。

operator func *

public operator func *(r: Duration): Duration

功能：重载操作符 *，实现 "Int64 * Duration = Duration"，返回新的 Duration 实例表示积。

例如 2 * Duration.second 返回表示时间间隔为 2 秒的 Duration 实例。

参数：

r：Duration 实例，乘法的右操作数

返回值：乘法运算的结果

异常：

ArithmeticException：当相乘后的结果超出 Duration 的表示范围时，抛出异常

extend Float64 <: DurationExtension

extend Float64 <: DurationExtension

拓展了 Float64 类型作为左操作数和 Duration 类型作为右操作数的乘法运算。

operator func *

public operator func *(r: Duration): Duration

功能：重载操作符 *，实现 "Float64 * Duration = Duration"，返回新的 Duration 实例表示积。由于 Float64 的精度受限，当 Duration 超过一定范围时，结果会不准确。

参数：

r：Duration 实例，乘法的右操作数

返回值：乘法运算的结果

异常：

ArithmeticException：当相乘后的结果超出 Duration 的表示范围时，抛出异常

class TimeZone

public class TimeZone <: ToString & Equatable<TimeZone> {
    public static let UTC: TimeZone
    public static let Local: TimeZone
    public init(id: String, offset: Duration)
}

类 TimeZone 表示了具体的时区信息，提供从系统加载时区、自定义时区等功能。

时区信息包含对应地区的夏令时、时区偏移量等信息。

类 TimeZone 提供的 API 如下所示：

init

public init(id: String, offset: Duration)

功能：使用参数 id 和 offset 指定的时区 id 和偏移构造一个自定义 TimeZone 实例。其中，offset 精度为秒，相对于 UTC 时区向东为正，有效区间为 [-24:59:59, 25:59:59]。

参数：

id：时区 id
offset：时区偏移

异常：

IllegalArgumentException：输入 id 为空字符串，或 offset 无效时抛出异常

Local

public static let Local: TimeZone

功能：获取本地时区。此函数根据系统环境变量 TZ 获取时区 id，并从系统时区文件中加载时区；若未设置 TZ 环境变量或 TZ 环境变量为空，则加载名为 localtime 的本地时区。环境变量 TZ 的取值为时区 id 格式，如 "Asia/Shanghai"，该格式中使用的正斜杠符合标准时区 id 规范，不因操作系统不同而改变。系统时区文件依赖路径 "/usr/share/zoneinfo"，本地时区文件依赖 "/etc/localtime"，若系统中上述依赖的路径不存在，则返回 UTC；通过时区 id 方式加载时区时，若无法从相应路径中找到 id 对应的时区文件时，则返回 UTC；通过本地时区文件方式加载时区时，若本地时区文件未链接到时区文件时，则返回 UTC 。

func load

public static func load(id: String): TimeZone

功能：从系统中加载参数 id 指定的时区，其格式举例 "Asia/Shanghai"，该格式中使用的正斜杠符合标准时区 id 规范，不因操作系统不同而改变（windows 需要用户自行下载 IANA 时区文件）如果存在名为 CJ_TZPATH 的环境变量，则优先使用环境变量指定的根路径加载时区文件如果通过分隔符(Linux 是 ":" ; Windows 是 ";" )设定了多个环境变量值，将会按照分隔路径的先后顺序依次查找时区文件，并加载第一个找到的时区文件。需要注意的是，如果设定了有效的环境变量，将不会去查找系统的时区文件，环境变量中查找不到，将会抛出异常环境变量未定义又或者指向一个空字符串时，该环境变量视作无效，按照默认路径 "/usr/share/zoneinfo" 寻找时区文件当参数 id 为 "UTC" 时，返回 TimeZone.UTC；当参数 id 为 "Local" 时，返回 TimeZone.Local。此函数加载成功时获得 TimeZone 实例，否则抛出异常。

参数：

id：时区 id 的字符串表示

返回值：加载的时区

异常：

IllegalArgumentException：当参数 id 为空，或长度超过 4096，或不合法时，抛出异常
InvalidDataException：如果时区文件加载失败，则抛出异常(如找不到文件，文件解析失败等)

func loadFromPaths

public static func loadFromPaths(id: String, tzpaths: Array<String>): TimeZone

功能：从参数 tzpaths 指定的路径中加载参数 id 指定的时区。由参数 tzpaths 指定根路径（Linux 系统例如 "/root/user/location/"，Windows 系统例如 "C:\Users\location"），由参数 id 指定时区 id，其格式举例 "Asia/Shanghai"，该格式中使用的正斜杠符合标准时区 id 规范，不因操作系统不同而改变。加载时区文件时，将按照 Array 内部存放的时区文件路径顺序读取。例如：Array 中保存了三个路径分别为 "/root/user01/location/"，"/root/user02/location/"，"/root/user03/location/"，三个路径底下均保存了 Asia/Shanghai 的时区文件，但是实例化时，获取的信息是由 /root/user01/location/ 路径提供的，加载成功时获得 TimeZone 实例，否则抛出异常。

参数：

tzpaths：时区文件存放的路径集合，其包内时区文件需要满足 IANA 时区文件格式：https://datatracker.ietf.org/doc/html/rfc8536
id：存在的时区 id

返回值：加载的时区

异常：

IllegalArgumentException：当 id 为空，或长度超过 4096，或不合法时，抛出异常
InvalidDataException：如果时区文件加载失败，则抛出异常(如找不到文件，文件解析失败等)

func loadFromTZData

public static func loadFromTZData(id: String, data: Array<UInt8>): TimeZone

功能：使用参数 id 和 data 指定的时区 id 和时区数据构造一个自定义 TimeZone 实例，id 可以是任何合法字符串，data 需要满足 IANA 时区文件格式，加载成功时获得 TimeZone 实例，否则抛出异常。

参数：

id：时区 id
data：满足 IANA 时区数据库格式的数据

返回值：加载的时区

异常：

IllegalArgumentException：当 id 为空时，抛出异常
InvalidDataException：如果 data 解析失败，则抛出异常

func toString

public func toString(): String

功能：获取本 TimeZone 实例时区 id 的字符串表示。

返回值：时区 id 的字符串表示

operator func ==

public operator func ==(r: TimeZone): Bool

功能：判断当前 TimeZone 实例是否等于 r，两个 TimeZone 的引用相同时，返回 true；反之，返回 false。

参数：

r：TimeZone 实例，== 运算的右操作数

返回值：当前 TimeZone 实例是否等于 r

operator func !=

public operator func !=(r: TimeZone): Bool

功能：判断当前 TimeZone 实例是否不等于 r，两个 TimeZone 的引用相同时，返回 false；反之，返回 true。

参数：

r：TimeZone 实例，!= 运算的右操作数

返回值：当前 TimeZone 实例是否不等于 r

class TimeParseException

public class TimeParseException <: Exception {
    public init()
    public init(message: String)
}

异常类，表示解析时间字符串发生错误。

init

public init()

功能：构造一个 TimeParseException 实例。

init

public init(message: String)

功能：根据参数 message 指定的异常信息，构造一个 TimeParseException 实例。

参数：

message：预定义消息

class InvalidDataException

public class InvalidDataException <: Exception {
    public init()
    public init(message: String)
}

异常类，表示加载时区发生错误。

init

public init()

功能：构造一个 InvalidDataException 实例。

init

public init(message: String)

功能：根据参数 message 指定的异常信息，构造一个 InvalidDataException 实例。

参数：

message：预定义消息

struct DateTime

public struct DateTime <: ToString & Hashable & Comparable<DateTime>

DateTime 表示日期时间，可表示至纳秒，受时区影响。可表示的时间区间为 [-999,999,999-01-01T00:00:00.000000000, 999,999,999-12-31T23:59:59.999999999]，该表示范围不受时区影响。主要提供了时间的读取和计算、基于时区的时间转换、序列化和反序列化等功能。

DateTime 的比较是基于去除时区影响的时间，即实例对应的零时区的时间。如表示东8区（+8）2023年4月13日8时0分0秒 与西5区（-5）2023年4月12日19时0分0秒 的 DateTime 实例是相等的。

以下为 DateTime 中 now 函数获取当前时间使用的系统调用函数：

系统	系统调用函数	时钟类型
Linux	clock_gettime	CLOCK_REALTIME
Windows	clock_gettime	CLOCK_REALTIME
macOS	clock_gettime	CLOCK_REALTIME

DateTime 提供的 API 如下所示：

prop UnixEpoch

public static prop UnixEpoch: DateTime

功能：Unix 时间纪元 - 1970-01-01T00:00:00Z。

prop year

public prop year: Int64

功能：获取当前 DateTime 实例的年份。

返回值：当前 DateTime 实例的年份

prop month

public prop month: Month

功能：获取当前 DateTime 实例的月份。

返回值：当前 DateTime 实例的月

prop monthValue

public prop monthValue: Int64

功能：获取当前 DateTime 实例的月份取值。

返回值：当前 DateTime 实例的月份取值

prop dayOfMonth

public prop dayOfMonth: Int64

功能：获取当前 DateTime 实例以月算的天数。

返回值：当前 DateTime 实例以月算的天数

prop dayOfWeek

public prop dayOfWeek: DayOfWeek

功能：获取当前 DateTime 实例以周算的天数。

返回值：当前 DateTime 实例以周算的天数

prop dayOfYear

public prop dayOfYear: Int64

功能：获取当前 DateTime 实例以年算的天数。

返回值：当前 DateTime 实例以年算的天数

prop hour

public prop hour: Int64

功能：获取当前 DateTime 实例的小时。

返回值：当前 DateTime 实例的小时

prop minute

public prop minute: Int64

功能：获取当前 DateTime 实例的分钟。

返回值：当前 DateTime 实例的分钟

prop second

public prop second: Int64

功能：获取当前 DateTime 实例的秒。

返回值：当前 DateTime 实例的秒

prop nanosecond

public prop nanosecond: Int64

功能：获取当前 DateTime 实例的纳秒。

返回值：当前 DateTime 实例的纳秒

prop isoWeek

public prop isoWeek: (Int64, Int64)

功能：获取基于 ISO8601 标准的年份和基于年的周数。

返回值：基于 ISO8601 标准的年份和基于年的周数

prop zone

public prop zone: TimeZone

功能：获取当前 DateTime 实例所关联的时区。

返回值：前 DateTime 实例所关联的时区

prop zoneId

public prop zoneId: String

功能：获取当前 DateTime 实例所关联的 TimeZone 实例的时区 id。返回值：时区 id 的字符串表示

prop zoneOffset

public prop zoneOffset: Duration

功能：获取当前 DateTime 实例所关联的 TimeZone 实例的时间偏移。返回值：时间偏移表示的时间间隔

func now

public static func now(timeZone!: TimeZone = TimeZone.Local): DateTime

功能：获取参数 timeZone 指定时区的当前时间。该方法获取的当前时间受系统时间影响，如存在使用不受系统时间影响的计时场景，可使用 MonoTime.now() 替代。

参数：

timeZone：时区，默认为本地时区

返回值：返回指定时区当前时间

func nowUTC

public static func nowUTC(): DateTime

功能：获取 UTC 时区的当前时间。该方法获取的当前时间受系统时间影响，如存在使用不受系统时间影响的计时场景，可使用 MonoTime.now() 替代。

返回值：UTC 时区当前时间

func fromUnixTimeStamp

public static func fromUnixTimeStamp(d: Duration): DateTime

功能：获取自 UnixEpoch 开始参数 d 指定时间间隔后的日期时间。

参数：

d：时间间隔

返回值：自 UnixEpoch 开始的指定 d 后的日期时间

异常：

ArithmeticException：当结果超过日期时间的表示范围时，抛出异常

func ofEpoch

public static func ofEpoch(second!: Int64, nanosecond!: Int64): DateTime

功能：根据入参 second 和 nanosecond 构造 DateTime 实例。入参 second 表示 unix 时间的秒部分，nanosecond 表示 unix 时间的纳秒部分。unix 时间以 UnixEpoch 开始计算，nanosecond 的范围不可以超过[0, 999,999,999]，否则抛出异常。

参数：

second：unix 时间的秒部分
nanosecond：unix 时间的纳秒部分，范围不可以超过[0, 999,999,999]

返回值：返回自 UnixEpoch 开始的指定 second 和 nanosecond 后的时间

异常：

IllegalArgumentException：当 nanosecond 值超出指定范围时，抛出异常
ArithmeticException：当结果超过日期时间的表示范围时，抛出异常

func of

public static func of(
    year!: Int64,
    month!: Int64,
    dayOfMonth!: Int64,
    hour!: Int64 = 0,
    minute!: Int64 = 0,
    second!: Int64 = 0,
    nanosecond!: Int64 = 0,
    timeZone!: TimeZone = TimeZone.Local
): DateTime

功能：根据参数指定的年、月、日、时、分、秒、纳秒、时区构造 DateTime 实例。

参数：

year：年，范围[-999,999,999, 999,999,999]
month：月，范围[1, 12]
dayOfMonth：日，范围[1, 31]，最大取值需要跟 month 匹配，可能是 28、29、30、31
hour：时，范围[0, 23]
minute：分，范围[0, 59]
second：秒，范围[0, 59]
nanosecond：纳秒，范围[0, 999,999,999]
timeZone：时区

返回值：根据指定参数构造的 DateTime 实例

异常：

IllegalArgumentException：当参数值超出指定范围，抛出异常

func of

public static func of(
    year!: Int64,
    month!: Month,
    dayOfMonth!: Int64,
    hour!: Int64 = 0,
    minute!: Int64 = 0,
    second!: Int64 = 0,
    nanosecond!: Int64 = 0,
    timeZone!: TimeZone = TimeZone.Local
): DateTime

功能：根据参数指定的年、月、日、时、分、秒、纳秒、时区构造 DateTime 实例。

参数：

year：年，范围[-999,999,999, 999,999,999]
month：月，Month 类型
dayOfMonth：日，范围[1, 31]，最大取值需要跟 month 匹配，可能是 28、29、30、31
hour：时，范围[0, 23]
minute：分，范围[0, 59]
second：秒，范围[0, 59]
nanosecond：纳秒，范围[0, 999,999,999]
timeZone：时区

返回值：根据指定参数构造的 DateTime 实例

异常：

IllegalArgumentException：当参数值超出指定范围，抛出异常

func ofUTC

public static func ofUTC(
    year!: Int64,
    month!: Int64,
    dayOfMonth!: Int64,
    hour!: Int64 = 0,
    minute!: Int64 = 0,
    second!: Int64 = 0,
    nanosecond!: Int64 = 0
): DateTime

功能：根据参数指定的年、月、日、时、分、秒、纳秒构造 UTC 时区 DateTime 实例。

参数：

year：年，范围[-999,999,999, 999,999,999]
month：月，范围[1, 12]
dayOfMonth：日，范围[1, 31]，最大取值需要跟 month 匹配，可能是 28、29、30、31
hour：时，范围[0, 23]
minute：分，范围[0, 59]
second：秒，范围[0, 59]
nanosecond：纳秒，范围[0, 999,999,999]

返回值：根据指定参数构造的 UTC 时区 DateTime 实例

异常：

IllegalArgumentException：当参数值超出指定范围时，抛出异常

func ofUTC

public static func ofUTC(
    year!: Int64,
    month!: Month,
    dayOfMonth!: Int64,
    hour!: Int64 = 0,
    minute!: Int64 = 0,
    second!: Int64 = 0,
    nanosecond!: Int64 = 0
): DateTime

功能：根据参数指定的年、月、日、时、分、秒、纳秒构造 UTC 时区 DateTime 实例。

参数：

year：年，范围[-999,999,999, 999,999,999]
month：月，Month 类型
dayOfMonth：日, 范围[1, 31]，最大取值需要跟 month 匹配，可能是 28、29、30、31
hour：时，范围[0, 23]
minute：分，范围[0, 59]
second：秒，范围[0, 59]
nanosecond：纳秒，范围[0, 999,999,999]

返回值：根据指定参数构造的 UTC 时区 DateTime 实例

异常：

IllegalArgumentException：当参数值超出指定范围时，抛出异常

func parse

public static func parse(str: String): DateTime

功能：从参数 str 中解析得到时间，解析成功时返回 DateTime 实例。

参数：

str：时间字符串，格式为 RFC3339 中 date-time 格式，可包含小数秒，如 "2023-04-10T08:00:00[.123456]+08:00"([] 中的内容表示可选项)

返回值：从参数 str 中解析出的 DateTime 实例

异常：

TimeParseException：无法正常解析时，抛出异常

func parse

public static func parse(str: String, format: String): DateTime

功能：根据 format 指定的时间格式，从字符串 str 中解析得到时间，解析成功时返回 DateTime 实例，解析具体规格可见下文“从字符串中解析得到时间”模块。

参数：

str：时间字符串，例如："2023/04/10 08:00:00 +08:00"
format：时间字符串的格式，例如："yyyy/MM/dd HH:mm:ss OOOO"

返回值：根据参数 format 指定的时间格式，从参数 str 中解析出的 DateTime 实例

异常：

TimeParseException：当无法正常解析时，或存在同一 format 的多次取值时，抛出异常
IllegalArgumentException：当 format 格式不正确时，抛出异常

func inUTC

public func inUTC(): DateTime

功能：获取当前 DateTime 实例在 UTC 时区的时间。

返回值：当前 DateTime 实例在 UTC 时区的时间

异常：

ArithmeticException：当返回的 DateTime 实例表示的日期时间超过表示范围时，抛出异常

func inLocal

public func inLocal(): DateTime

功能：获取当前 DateTime 实例在本地时区的时间。

返回值：当前 DateTime 实例在本地时区的时间

异常：

ArithmeticException：当返回的 DateTime 实例表示的日期时间超过表示范围时，抛出异常

func inTimeZone

public func inTimeZone(timeZone: TimeZone): DateTime

功能：获取当前 DateTime 实例在参数 timeZone 指定时区的时间。

参数：

timeZone：目标时区

返回值：当前 DateTime 实例在参数 timezone 指定时区的时间

异常：

ArithmeticException：当返回的 DateTime 实例表示的日期时间超过表示范围时，抛出异常

func toUnixTimeStamp

public func toUnixTimeStamp(): Duration

功能：获取当前实例自 UnixEpoch 的时间间隔。

返回值：当前实例自 UnixEpoch 的时间间隔

func toString

public func toString(): String

功能：返回一个表示当前 DateTime 实例的字符串，其格式为 RFC3339 中 date-time 格式，如果时间包含纳秒信息（不为零），会打印出小数秒。

返回值：当前 DateTime 实例的字符串表示

func toString

public func toString(format: String): String

功能：返回一个表示当前 DateTime 实例的字符串，其格式由参数 format 指定。

参数：

format：返回字符串的格式，其格式可为 "yyyy/MM/dd HH:mm:ss OOOO"

返回值：当前 DateTime 实例在 format 指定格式下的字符串

异常：

IllegalArgumentException：当 format 格式不正确时，抛出异常

func hashCode

public func hashCode(): Int64

功能：获取当前 DateTime 实例的哈希值。

返回值：哈希值

func addYears

public func addYears(n: Int64): DateTime

功能：获取当前 DateTime 实例 n 年之后的时间，返回新的 DateTime 实例。

注意：由于年的间隔不固定，若设 dt 表示 “2020年2月29日”，dt.addYears(1) 不会返回非法日期“2021年2月29日”。为了尽量返回有效的日期，会偏移到当月最后一天，返回 “2021年2月28日”。

参数：

n：自当前 DateTime 实例后多少年的数量

返回值：当前 DateTime 实例 n 年后的时间

异常：

ArithmeticException：当前 DateTime 实例 n 年后的日期时间超过表示范围时，抛出异常

func addMonths

public func addMonths(n: Int64): DateTime

功能：获取当前 DateTime 实例 n 月之后的时间，返回新的 DateTime 实例。

注意：由于月的间隔不固定，若设 dt 表示 “2020年3月30日”，dt.addMonths(1) 不会返回非法日期“2020年3月31日”。为了尽量返回有效的日期，会偏移到当月最后一天，返回“2020年4月30日”。

参数：

n：自当前 DateTime 实例后多少月的数量

返回值：当前 DateTime 实例 n 月后的时间

异常：

ArithmeticException：当前 DateTime 实例 n 月后的日期时间超过表示范围时，抛出异常

func addWeeks

public func addWeeks(n: Int64): DateTime

功能：获取当前 DateTime 实例 n 周之后的时间，返回新的 DateTime 实例。

参数：

n：自当前 DateTime 实例后多少周的数量

返回值：当前 DateTime 实例 n 周后的时间

异常：

功能：获取入参 n 周之后的时间，返回新的 DateTime 实例。

func addDays

public func addDays(n: Int64): DateTime

功能：获取当前 DateTime 实例 n 天之后的时间，返回新的 DateTime 实例。

参数：

n：自当前 DateTime 实例后多少天的数量

返回值：当前 DateTime 实例 n 天后的时间

异常：

ArithmeticException：当前 DateTime 实例 n 天后的日期时间超过表示范围时，抛出异常

func addHours

public func addHours(n: Int64): DateTime

功能：获取当前 DateTime 实例 n 小时之后的时间，返回新的 DateTime 实例。

参数：

n：自当前 DateTime 实例后多少小时的数量

返回值：当前 DateTime 实例 n 小时后的时间

异常：

ArithmeticException：当前 DateTime 实例 n 小时后的日期时间超过表示范围时，抛出异常

func addMinutes

public func addMinutes(n: Int64): DateTime

功能：获取当前 DateTime 实例 n 分钟之后的时间，返回新的 DateTime 实例。

参数：

n：自当前 DateTime 实例后多少分钟的数量

返回值：当前 DateTime 实例 n 分钟后的时间

异常：

ArithmeticException：当前 DateTime 实例 n 分钟后的日期时间超过表示范围时，抛出异常

func addSeconds

public func addSeconds(n: Int64): DateTime

功能：获取当前 DateTime 实例 n 秒之后的时间，返回新的 DateTime 实例。

参数：

n：自当前 DateTime 实例后多少秒的数量

返回值：当前 DateTime 实例 n 秒后的时间

异常：

ArithmeticException：当前 DateTime 实例 n 秒后的日期时间超过表示范围时，抛出异常

func addNanoseconds

public func addNanoseconds(n: Int64): DateTime

功能：获取当前 DateTime 实例 n 纳秒之后的时间，返回新的 DateTime 实例。

参数：

n：自当前 DateTime 实例后多少纳秒的数量

返回值：当前 DateTime 实例 n 纳秒后的时间

异常：

ArithmeticException：当前 DateTime 实例 n 纳秒后时间的日期时间超过表示范围时，抛出异常

operator func +

public operator func +(r: Duration): DateTime

功能：重载操作符 +，实现 "DateTime + Duration = DateTime"，返回一个新的 DateTime 实例表示参数 r 指定时间间隔后的日期时间。

参数：

r：时间间隔，加法的右操作数

返回值：参数 r 指定时间间隔后的日期时间

异常：

ArithmeticException：当结果超过日期时间的表示范围时，抛出异常

operator func -

public operator func -(r: Duration): DateTime

功能：重载操作符 -，实现 "DateTime - Duration = DateTime"，返回一个新的 DateTime 实例表示参数 r 指定时间间隔前的时间。

参数：

r：时间间隔，减法的右操作数

返回值：参数 r 指定时间间隔前的时间

异常：

ArithmeticException：当结果超过日期时间的表示范围时，抛出异常

operator func -

public operator func -(r: DateTime): Duration

功能：重载操作符 -，实现 "DateTime - DateTime = Duration"，返回一个 Duration 实例表示两个 DateTime 实例相距的时间间隔。若参数 r 表示的时间早于当前 DateTime 实例，结果为正，晚于为负，等于为 0。

参数：

r：时间，减法的右操作数

返回值：当前 DateTime 实例与参数 r 相距的时间间隔

operator func ==

public operator func ==(r: DateTime): Bool

功能：重载操作符 ==，实现 "DateTime == DateTime" 运算，返回当前 DateTime 实例是否等于 r。

参数：

r：DateTime 实例，== 运算的右操作数

返回值：当前 DateTime 实例是否等于 r

operator func !=

public operator func !=(r: DateTime): Bool

功能：重载操作符 !=，实现 "DateTime != DateTime" 运算，返回当前 DateTime 实例是否不等于 r。

参数：

r：DateTime 实例，!= 运算的右操作数

返回值：当前 DateTime 实例是否不等于 r

operator func >=

public operator func >=(r: DateTime): Bool

功能：重载操作符 >=，实现 "DateTime >= DateTime" 运算，返回当前 DateTime 实例是否晚于或等于 r。

参数：

r：DateTime 实例，>= 运算的右操作数

返回值：当前 DateTime 实例是否晚于或等于 r

operator func >

public operator func >(r: DateTime): Bool

功能：重载操作符 >，实现 "DateTime > DateTime" 运算，返回当前 DateTime 实例是否晚于 r。

参数：

r：DateTime 实例，> 运算的右操作数

返回值：当前 DateTime 实例是否晚于 r

operator func <=

public operator func <=(r: DateTime): Bool

功能：重载操作符 <=，实现 "DateTime <= DateTime" 运算，返回当前 DateTime 实例是否早于或等于 r。

参数：

r：DateTime 实例，<= 运算的右操作数

返回值：当前 DateTime 实例是否早于或等于 r

operator func <

public operator func <(r: DateTime): Bool

功能：重载操作符 <，实现 "DateTime < DateTime" 运算，返回当前 DateTime 实例是否早于 r。

参数：

r：DateTime 实例，< 运算的右操作数

返回值：当前 DateTime 实例是否早于 r

func compare

public func compare(rhs: DateTime): Ordering

功能：判断一个 DateTime 实例与参数 rhs 的大小关系。如果大于，返回 Ordering.GT；如果等于，返回 Ordering.EQ；如果小于，返回 Ordering.LT。

参数：

rhs：参与比较的 DateTime 实例

返回值：当前 DateTime 实例与 rhs 大小关系

struct MonoTime

public struct MonoTime <: Hashable & Comparable<MonoTime>

MonoTime 表示单调时间，是一个用来衡量经过时间的时钟，类似于一直运行的秒表，精度为纳秒。可表示的范围为 Duration.Zero 至 Duration.Max，数值表示为[0, 2⁶³)（单位为秒）。

通过 now 方法创建的 MonoTime 总是晚于先使用该方式创建的 MonoTime，常用于性能测试和时间优先的任务队列。

以下为 MonoTime 中 now 函数获取当前时间使用的系统调用函数：

系统	系统调用函数	时钟类型
Linux	clock_gettime	CLOCK_MONOTONIC
Windows	clock_gettime	CLOCK_MONOTONIC
macOS	clock_gettime	CLOCK_MONOTONIC

MonoTime 提供的 API 如下所示：

func now

public static func now(): MonoTime

功能：获取与当前时间对应的 MonoTime。

返回值：与当前时间对应的 MonoTime

operator func +

public operator func +(r: Duration): MonoTime

功能：重载操作符 +，实现 "MonoTime + Duration = MonoTime"，返回经过 r 表示时间间隔后的单调时间。

参数：

r：时间间隔，加法的右操作数

返回值：参数 r 表示时间间隔后的单调时间

异常：

ArithmeticException：当结果超过单调时间的表示范围时，抛出异常

operator func -

public operator func -(r: Duration): MonoTime

功能：重载操作符 -，实现 "MonoTime - Duration = MonoTime"，返回经过 r 表示时间间隔前的单调时间。

参数：

r：时间间隔，减法的右操作数

返回值：参数 r 表示时间间隔前的单调时间

异常：

ArithmeticException：当结果超过单调时间的表示范围时，抛出异常

operator func -

public operator func -(r: MonoTime): Duration

功能：重载操作符 -，实现 "MonoTime - MonoTime = Duration"，返回当前实例距 r 经过的时间间隔。

参数：

r：单调时间，减法的右操作数

返回值：当前实例距 r 经过的时间间隔

operator func ==

public operator func ==(r: MonoTime): Bool

功能：重载操作符 ==，实现 "MonoTime == MonoTime" 运算，返回当前 MonoTime 实例是否等于 r。

参数：

r：单调时间，== 运算的右操作数

返回值：当前 MonoTime 实例是否等于 r，若等于，则返回 ture；否则，返回 false

operator func !=

public operator func !=(r: MonoTime): Bool

功能：重载操作符 !=，实现 "MonoTime != MonoTime" 运算，返回当前 MonoTime 实例是否不等于 r。

参数：

r：单调时间，!= 运算的右操作数

返回值：当前 MonoTime 实例是否不等于 r，若不等于，则返回 true；否则，返回 false

operator func >=

public operator func >=(r: MonoTime): Bool

功能：重载操作符 >=，实现 "MonoTime >= MonoTime" 运算，返回当前 MonoTime 实例是否晚于或等于 r。

参数：

r：单调时间，>= 运算的右操作数

返回值：当前 MonoTime 实例是否晚于或等于 r，若晚于或等于，则返回 true；否则，返回 false

operator func >

public operator func >(r: MonoTime): Bool

功能：重载操作符 >，实现 "MonoTime > MonoTime" 运算，返回当前 MonoTime 实例是否晚于 r。

参数：

r：单调时间，> 运算的右操作数

返回值：当前 MonoTime 实例是否早于 r，若晚于，则返回 true；否则，返回 false

operator func <=

public operator func <=(r: MonoTime): Bool

功能：重载操作符 <=，实现 "MonoTime <= MonoTime" 运算，返回当前 MonoTime 实例是否晚于或等于 r。

参数：

r：单调时间，<= 运算的右操作数

返回值：当前 MonoTime 实例是否晚于或等于 r，若晚于或等于，则返回 true；否则，返回 false

operator func <

public operator func <(r: MonoTime): Bool

功能：重载操作符 <，实现 "MonoTime < MonoTime" 运算，返回当前 MonoTime 实例是否晚于 r。

参数：

r：单调时间，< 运算的右操作数

返回值：当前 MonoTime 实例是否晚于 r，若晚于，则返回 true；否则，返回 false

func compare

public func compare(rhs: MonoTime): Ordering

功能：判断一个 MonoTime 实例与参数 rhs 的大小关系。如果大于，返回 Ordering.GT；如果等于，返回 Ordering.EQ；如果小于，返回 Ordering.LT。

参数：

rhs：参与比较的 MonoTime 实例

返回值：当前 MonoTime 实例与 rhs 大小关系

func hashCode

public func hashCode(): Int64

功能：获取当前 MonoTime 实例的哈希值。

返回值：哈希值

enum Month

public enum Month <: ToString {
    | January
    | February
    | March
    | April
    | May
    | June
    | July
    | August
    | September
    | October
    | November
    | December
}

枚举类型 Month 用以表示月份，并提供与 Int64 类型的相互转换功能。

枚举类型 Month 提供的 API 如下所示：

January

January

功能：构造一个 Month 实例，表示一月。

February

February

功能：构造一个 Month 实例，表示二月。

March

March

功能：构造一个 Month 实例，表示三月。

April

April

功能：构造一个 Month 实例，表示四月。

May

May

功能：构造一个 Month 实例，表示五月。

June

June

功能：构造一个 Month 实例，表示六月。

July

July

功能：构造一个 Month 实例，表示七月。

August

August

功能：构造一个 Month 实例，表示八月。

September

September

功能：构造一个 Month 实例，表示九月。

October

October

功能：构造一个 Month 实例，表示十月。

November

November

功能：构造一个 Month 实例，表示十一月。

December

December

功能：构造一个 Month 实例，表示十二月。

func of

public static func of(mon: Int64): Month

功能：获取参数 mon 对应 Month 类型实例。

参数：

mon：整数形式的月，合法范围为 [1, 12]，分别表示一年中的十二个月

返回值：参数 mon 对应的 Month 类型实例

异常：

IllegalArgumentException：当参数 mon 不在 [1, 12] 范围内时，抛出异常

func value

public func value(): Int64

功能：获取当前 Month 实例的整数表示，一月至十二月分别表示为 1 至 12。

返回值：当前 Month 实例的整数表示

func toString

public func toString(): String

功能：返回当前 Month 实例的字符串表示。

返回值：当前 Month 实例的字符串表示

operator func +

public operator func +(n: Int64): Month

功能：重载操作符 +，实现 "Month + Int64 = Month"，表示 n 月之后的日历月份。例如，一月的 12 个月后为一月。

参数：

n：后多少月的数量，加法的右操作数

返回值：n 月后的月份

operator func -

public operator func -(n: Int64): Month

功能：重载操作符 -，实现 "Month - Int64 = Month"，表示 n 月前的日历月份。例如，一月的 12 个月前为一月。

参数：

n：前多少月的数量，减法的右操作数

返回值：n 月前的月份

operator func ==

public operator func ==(r: Month): Bool

功能：重载操作符 ==，实现 "Month == Month" 运算，返回当前 Month 实例是否等于 r。

参数：

r：Month 实例，== 运算的右操作数`

返回值：当前 Month 实例是否等于 r

operator func !=

public operator func !=(r: Month): Bool

功能：重载操作符 !=，实现 "Month != Month" 运算，返回当前 Month 实例是否不等于 r。

参数：

r：Month 实例，!= 运算的右操作数

返回值：当前 Month 实例是否不等于 r

enum DayOfWeek

public enum DayOfWeek <: ToString {
    | Sunday
    | Monday
    | Tuesday
    | Wednesday
    | Thursday
    | Friday
    | Saturday
}

枚举类型 DayOfWeek 用以表示一周中的某一天，并提供与 Int64 类型的相互转换功能。

枚举类型 DayOfWeek 提供的 API 如下所示：

Sunday

Sunday

功能：构造一个 DayOfWeek 实例，表示星期天。

Monday

Monday

功能：构造一个 DayOfWeek 实例，表示星期一。

Tuesday

Tuesday

功能：构造一个 DayOfWeek 实例，表示星期二。

Wednesday

Wednesday

功能：构造一个 DayOfWeek 实例，表示星期三。

Thursday

Thursday

功能：构造一个 DayOfWeek 实例，表示星期四。

Friday

Friday

功能：构造一个 DayOfWeek 实例，表示星期五。

Saturday

Saturday

功能：构造一个 DayOfWeek 实例，表示星期六。

func of

public static func of(dayOfWeek: Int64): DayOfWeek

功能：获取参数 dayOfWeek 对应 DayOfWeek 实例。

参数：

dayOfWeek：周几的整数表示，合法范围为 [0, 6]。其中，0 表示周日，1 至 6 表示周一至周六。

返回值：参数 dayOfWeek 对应的 DayOfWeek 实例

异常：

IllegalArgumentException：当 dayOfWeek 不在 [0, 6] 范围内时，抛出异常

func value

public func value(): Int64

功能：获取当前 DayOfWeek 实例的整数表示，周日表示为 0，周一至周六表示为 1 至 6。

返回值：当前 DayOfWeek 实例的整数表示

func toString

public func toString(): String

功能：返回当前 DayOfWeek 实例的字符串表示。

返回值：当前 DayOfWeek 实例的字符串表示

operator func ==

public operator func ==(r: DayOfWeek): Bool

功能：重载操作符 ==，实现 "DayOfWeek == DayOfWeek" 运算，返回当前 DayOfWeek 实例是否等于 r。

参数：

r：DayOfWeek 实例，== 的右操作数

返回值：当前 DayOfWeek 实例是否等于 r

operator func !=

public operator func !=(r: DayOfWeek): Bool

功能：重载操作符 !=，实现 "DayOfWeek != DayOfWeek" 运算，返回当前 DayOfWeek 实例是否不等于 r。

参数：

r：DayOfWeek 实例，!= 的右操作数

返回值：当前 DayOfWeek 实例是否不等于 r

enum FormatStyle

public enum FormatStyle {
    | RFC3339
    | RFC1123
}

枚举类型 FormatStyle 用以表示时间标准化格式，并提供打印标准时间格式功能。

枚举类型 Month 提供的 API 如下所示：

RFC3339

RFC3339

功能：构造一个 FormatStyle 实例，表示 RFC3339 时间格式。

RFC1123

RFC1123

功能：构造一个 FormatStyle 实例，表示 RFC1123 时间格式。

func value

public func value(): String

功能：获取当前 FormatStyle 时间格式的字符串表示。

返回值：时间格式的字符串表示

示例

获取时间的详细信息

读取当前时间，分别获取年、月、日、时、分、秒、纳秒、时区 id、时区偏移、序列化字符串等信息示例。

代码如下：

from std import time.*

main(): Int64 {
    var now = DateTime.now()

    var yr = now.year
    var mon = now.month
    var day = now.dayOfMonth
    var hr = now.hour
    var min = now.minute
    var sec = now.second
    var ns = now.nanosecond
    var zoneId = now.zoneId
    var offset = now.zoneOffset
    var dayOfWeek = now.dayOfWeek
    var dayOfYear = now.dayOfYear
    var (isoYear, isoWeek) = now.isoWeek

    println("Now is ${yr}, ${mon}, ${day}, ${hr}, ${min}, ${sec}, ${ns}, ${zoneId}, ${offset}")
    println("now.toString() = ${now}")
    println("${dayOfWeek}, ${dayOfYear}th day, ${isoWeek}th week of ${isoYear}")

    return 0
}

运行结果如下：

Now is 2021, August, 5, 21, 8, 4, 662859318, CST, 8h
now.toString() = 2021-08-05T21:08:04+08:00
Thursday, 217th day, 31th week of 2021

同一时间在不同时区的墙上时间

初始化指定时间，并进行时区转换，打印同一时间在不同时区下的墙上时间。

代码如下：

from std import time.*

main(): Int64 {
    var t = DateTime.of(year: 2021, month: Month.August, dayOfMonth: 5)

    println("local zone: ${t}")
    println("utc zone: ${t.inUTC()}")

    return 0
}

运行结果如下：

local zone: 2021-08-05T00:00:00+08:00
utc zone: 2021-08-04T16:00:00Z

从字符串中解析得到时间

字符串解析时间有以下要求和说明：

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

以下为 parse 函数中参数 format 中字符解析的范围

基于 ISO-8601 标准的年：1 ~ 9 位 Y 表示

case 1 | 3 | 4 解析 4 位数年份，如 2023, 0001等

case 2 解析 2 位数年份，如 23, 69等，其中 xx >= 69的会解析为 19xx，否则为 20xx，负数同理

case 5 ~ 9 解析 length 位数年份

case _ 异常
月：1 ~ 4 位 M 表示

case 1 解析 1 ~ 2 位数字，如 1, 01, 11 等

case 2 解析 2 位数字，如 01, 11 等

case 3 解析简写的月，如 Jan, Dec 等

case 4 解析完整书写的月，如 January, December 等

case _ 异常
日：1 ~ 2 位 d 表示

case 1 解析 1 ~ 2 位数字，如 1, 01, 11 等

case 2 解析 2 位数字，如 01, 11 等

case _ 异常
时（24小时制）：1 ~ 2 位 H 表示

case 1 解析 1 ~ 2 位数字，如 0, 00, 23 等

case 2 解析 2 位数字，如 00, 23 等

case _ 异常
时（12小时制）：1 ~ 2 位 h 表示

case 1 解析 1 ~ 2 位数字，如 1, 01, 12 等

case 2 解析 2 位数字，如 01, 12 等

case _ 异常
分：1 ~ 2 位 m 表示

case 1 解析 1 ~ 2 位数字，如 0, 00, 08, 59 等

case 2 解析 2 位数字，如 00, 08, 59 等

case _ 异常
秒：1 ~ 2 位 s 表示

case 1 解析 1 ~ 2 位数字，如 0, 00, 08, 59 等

case 2 解析 2 位数字，如 00, 08, 59 等

case _ 异常
纳秒：1 ~ 3 位 S 表示

case 1 解析 3 位数字，如 001, 123 等作为毫秒

case 2 解析 6 位数字，如 000001, 123456 等作为微秒

case 3 解析 9 位数字，如 000000001, 123456789 等作为纳秒

case _ 异常
时区（偏移形式）：1 ~ 4 位 O 表示，范围:[-24:59:59, 25:59:59]

case 1 解析格式如：+08, -08 等

case 2 解析格式如：+08:00, -08:59 等

case 3 解析格式如：+08:00:00, -08:59:59 等

case 4 解析格式如：case2 或 case3 以及 Z

case _ 异常
时区（时区名和地点形式）：1 ~ 4 位 z 表示

case 1 解析格式如：CST, GMT 等可以通过 TimeZone.load("XXX") 得到

case 2 解析格式如：case1

case 3 解析格式如：case1

case 4 解析格式如：Asia/Shanghai, America/New_York 等可以通过 TimeZone.load("XXX") 得到

case _ 异常
时区（GMT偏移形式）：1 ~ 4 位 Z 表示

case 1 解析格式如：GMT+0, GMT+10 等

case 2 解析格式如：GMT+00:00, GMT+10:00 等

case 3 解析格式如：GMT+00:00:00, GMT+10:00:00 等

case 4 解析格式如：case2 或 case3

case _ 异常
一年中的第几天：1 ~ 2 位 D 表示

case 1 解析格式如：1, 01, 001 等 1 ~ 3 位数字

case 2 解析格式如：01, 001 等 2 ~ 3 位数字

case _ 异常
基于 ISO-8601 标准的周：1 ~ 2 位 W 表示

case 1 解析格式如：1, 01 等 1 ~ 2 位数字

case 2 解析格式如：01, 12 等 2 位数字

case _ 异常
一周的第几天：1 ~ 4 位 w 表示

case 1 解析 1 位数字，如 0, 6 等, 0 表示周日，其余表示周一至周六

case 2 解析 2 位数字，如 00, 06 等，00 表示周日，其余表示周一至周六

case 3 解析简写的周，如 Sun, Sat 等

case 4 解析完整书写的周，如 Sunday, Saturday 等

case _ 异常
纪年：1 ~ 3 位 G 表示

case 1 解析 A

case 2 解析 AD

case 3 解析 Anno Domini

case _ 异常
上下午：1 位 a 表示

case 1 解析 AM 或 PM

case _ 异常

下面是从字符串中解析得到时间，并输出的示例。

代码如下：

from std import time.*

main(): Int64 {
    var customPtn = "yyyy/MM/dd HH:mm:ss OO"
    var t1 = DateTime.parse("2021-08-05T21:08:04+08:00")
    var t2 = DateTime.parse("2021/08/05 21:08:04 +10:00", customPtn)

    println("t1.toString(customPtn) = ${t1.toString(customPtn)}")
    println("t2.toString() = ${t2}")

    return 0
}

运行结果如下：

t1.toString(customPtn) = 2021/08/05 21:08:04 +08:00
t2.toString() = 2021-08-05T21:08:04 +10:00

时间实例转换为字符串格式

以下为 toString 函数中参数 format 中字符输出的结果

公元年：1 ~ 9 位 y 表示
基于 ISO-8601 标准的年：1 ~ 9 位 Y 表示

case 1 | 3 | 4 输出最少 4 位数年份，如 2023, 0001，99999 等，不足 4 位则补 0

case 2 输出 2 位或 4 位以上个数年份，如 23, 69等，其中 [1969, 1999] 会输出为 [69, 99]，[2000, 2068] 会输出为 [00, 68]，负数同理，其余情况至少输出 4 位，不足 4 位则补 0

case 5 ~ 9 输出 length 位数年份，不足则补 0

case _ 异常
月：1 ~ 4 位 M 表示

case 1 输出 1 ~ 2 位数字，如 1, 11 等

case 2 输出 2 位数字，如 01, 11 等

case 3 输出简写的月，如 Jan, Dec 等

case 4 输出完整书写的月，如 January, December 等

case _ 异常
日：1 ~ 2 位 d 表示

case 1 输出 1 ~ 2 位数字，如 1, 11 等

case 2 解析 2 位数字，如 01, 11 等

case _ 异常
时（24小时制）：1 ~ 2 位 H 表示

case 1 输出 1 ~ 2 位数字，如 0, 23 等

case 2 输出 2 位数字，如 00, 23 等

case _ 异常
时（12小时制）：1 ~ 2 位 h 表示

case 1 输出 1 ~ 2 位数字，如 1, 12 等

case 2 输出 2 位数字，如 01, 12 等

case _ 异常
分：1 ~ 2 位 m 表示

case 1 输出 1 ~ 2 位数字，如 0, 59 等

case 2 解析 2 位数字，如 00, 08, 59 等

case _ 异常
秒：1 ~ 2 位 s 表示

case 1 输出 1 ~ 2 位数字，如 0, 59 等

case 2 输出 2 位数字，如 00, 08, 59 等

case _ 异常
纳秒：1 ~ 3 位 S 表示

case 1 输出 3 位数字，如 001, 123 等作为毫秒

case 2 输出 6 位数字，如 000001, 123456 等作为微秒

case 3 输出 9 位数字，如 000000001, 123456789 等作为纳秒

case _ 异常
时区（偏移形式）：1 ~ 4 位 O 表示

case 1 输出格式如：+08, -08 等，若偏移量不为整小时，则会截断

case 2 输出格式如：+08:00, -08:59 等，偏移量不为整分钟，则会截断

case 3 输出格式如：+08:00:00, -08:59:59 等

case 4 输出格式如：case2 或 case3, 偏移量为 0 时, 输出 Z

case _ 异常
时区（时区名和地点形式）：1 ~ 4 位 z 表示

case 1 输出格式如：CST, GMT 等

case 2 输出格式如：case1

case 3 输出格式如：case1

case 4 输出格式如：Asia/Shanghai, America/New_York 等

case _ 异常
时区（GMT偏移形式）：1 ~ 4 位 Z 表示

case 1 输出格式如：GMT+0, GMT+10 等

case 2 输出格式如：GMT+00:00, GMT+10:00 等

case 3 输出格式如：GMT+00:00:00, GMT+10:00:00 等

case 4 输出格式如：case2 或 case3

case _ 异常
一年中的第几天：1 ~ 2 位 D 表示

case 1 输出格式如：1, 12, 123 等 1 ~ 3 位数字

case 2 输出格式如：001, 012, 123 等 2 ~ 3 位数字

case _ 异常
基于 ISO-8601 标准的周：1 ~ 2 位 W 表示

case 1 输出格式如：1, 12 等 1 ~ 2 位数字

case 2 输出格式如：01, 12 等 2 位数字

case _ 异常
一周的第几天：1 ~ 4 位 w 表示

case 1 输出 1 位数字，如 0, 6 等, 0 表示周日，其余表示周一至周六

case 2 输出 2 位数字，如 00, 06 等, 00 表示周日，其余表示周一至周六

case 3 输出简写的周，如 Sun, Sat 等

case 4 输出完整书写的周，如 Sunday, Saturday 等

case _ 异常
纪年：1 ~ 3 位 G 表示

case 1 输出 A

case 2 输出 AD

case 3 输出 Anno Domini

case _ 异常
上下午：1 位 a 表示

case 1 输出 AM 或 PM

case _ 异常

下面是时间示例转为字符串，并输出的示例。

代码如下：

from std import time.*

main(): Int64 {
    var customPtn = "yyyy/MM/dd HH:mm:ss OO"
    var t = DateTime.of(
        year: 2023,
        month: 1,
        dayOfMonth: 23,
        hour: 4,
        minute: 56,
        second: 7,
        nanosecond: 89,
        timeZone: TimeZone.load("Asia/Shanghai")
    )

    println("t.toString(customPtn) = ${t.toString(customPtn)}")
    println("t.toString() = ${t}")

    return 0
}

运行结果如下：

t.toString(customPtn) = 2023/01/23 04:56:07 +08:00
t.toString() = 2023-01-23T04:56:07.89+08:00

DayOfWeek 的使用

初始化不同的 DayOfWeek，进行与 Int64 类型的互转、比较大小，打印其字符串表示等。

代码如下：

from std import time.*

main(): Int64 {
    var sat = DayOfWeek.Saturday
    var sun = DayOfWeek.of(0)

    println("sat.toString() = ${sat}")
    println("sun.toString() = ${sun}")

    println("sat.value() = ${sat.value()}")
    println("sun.value() = ${sun.value()}")

    println("sat == sun ? ${sat == sun}")

    return 0
}

运行结果如下：

sat.toString() = Saturday
sun.toString() = Sunday
sat.value() = 6
sun.value() = 0
sat == sun ? false

Month 的使用

初始化不同的 Month，进行与 Int64 类型的互转、算数运算、比较大小，打印其字符串表示等。

代码如下：

from std import time.*

main(): Int64 {
    var jan = Month.January
    var feb = Month.of(2)

    println("jan.toString() = ${jan}")
    println("feb.toString() = ${feb}")

    println("jan.value() = ${jan.value()}")
    println("feb.value() = ${feb.value()}")

    println("jan + 1 = ${jan + 1}")
    println("feb - 1 = ${feb - 1}")

    println("jan == feb ? ${jan == feb}")

    return 0
}

运行结果如下：

jan.toString() = January
feb.toString() = February
jan.value() = 1
feb.value() = 2
jan + 1 = February
feb - 1 = January
jan == feb ? false

Duration 的使用

初始化不同的 Duration，打印其字符串表示，并对其比较大小。

代码如下：

from std import time.*

main(): Int64 {
    var d1 = Duration.nanosecond * 10000
    var d2 = Duration.microsecond * 100
    var d3 = Duration.millisecond * 10
    var d4 = Duration.second
    var d5 = Duration.minute * 2
    var d6 = Duration.hour * 3

    println("d1 = ${d1}")
    println("d2 = ${d2}")
    println("d3 = ${d3}")
    println("d4 = ${d4}")
    println("d5 = ${d5}")
    println("d6 = ${d6}")

    println("in nanosecond, d1 = ${d1.toNanoseconds()}")
    println("in nanosecond, d2 = ${d2.toNanoseconds()}")
    println("in nanosecond, d3 = ${d3.toNanoseconds()}")
    println("in second, d4 = ${d4.toSeconds()}")
    println("in second, d4 = ${d5.toSeconds()}")
    println("in second, d4 = ${d6.toSeconds()}")

    println("d1 > d2 ? ${d1 > d2}")

    return 0
}

运行结果如下：

d1 = 10us
d2 = 100us
d3 = 10ms
d4 = 1s
d5 = 2m
d6 = 3h
in nanosecond, d1 = 10000
in nanosecond, d2 = 100000
in nanosecond, d3 = 10000000
in second, d4 = 1
in second, d4 = 120
in second, d4 = 10800
d1 > d2 ? false

TimeZone 的使用

通过不同方式初始化时区，对指定时间进行时区转换，打印同一时间在不同时区下的墙上时间。

代码如下：

from std import time.*

main(): Int64 {
    var utc = TimeZone.load("UTC")
    var local = TimeZone.load("Local")
    var newYork = TimeZone.load("America/New_York")

    println("utc.toString() = ${utc}")
    println("local.toString() = ${local}")
    println("newYork.toString() = ${newYork}")

    var t = DateTime.of(year: 2021, month: Month.August, dayOfMonth: 5)

    println("in utc zone, ${t.inTimeZone(utc)}")
    println("in local zone, ${t.inTimeZone(local)}")
    println("in newYork zone, ${t.inTimeZone(newYork)}")

    return 0
}

运行结果如下：

utc.toString() = UTC
local.toString() = Asia/Shanghai
newYork.toString() = America/New_York
in utc zone, 2021-08-04T16:00:00Z
in local zone, 2021-08-05T00:00:00+08:00
in newYork zone, 2021-08-04T12:00:00-04:00

仓颉用户手册