结构体

struct DateTime

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

功能：DateTime 表示日期时间，是一个描述某一时间点的时间类型，提供了基于时区的日期时间读取、计算、比较、转换，以及序列化和反序列化等功能。

  • DateTime 是不可变的类型，包含了日期，时间和时区信息。可表示的时间区间为 [-999,999,999-01-01T00:00:00.000000000, 999,999,999-12-31T23:59:59.999999999]，该区间适用于任何合法的时区。

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

    系统系统调用函数时钟类型
    Linuxclock_gettimeCLOCK_REALTIME
    Windowsclock_gettimeCLOCK_REALTIME
    macOSclock_gettimeCLOCK_REALTIME

父类型：

static prop UnixEpoch

public static prop UnixEpoch: DateTime

功能：获取 Unix 时间纪元，即表示零时区 1970年1月1日0时0分0秒0纳秒 的 DateTime 实例。

类型：DateTime

prop dayOfMonth

public prop dayOfMonth: Int64

功能：获取 DateTime 实例基于当前月第几日。

类型：Int64

prop dayOfWeek

public prop dayOfWeek: DayOfWeek

功能：获取 DateTime 实例基于当前周的第几日。

类型：DayOfWeek

prop dayOfYear

public prop dayOfYear: Int64

功能：获取 DateTime 实例基于当前年份的第几日。

类型：Int64

prop hour

public prop hour: Int64

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

类型：Int64

prop isoWeek

public prop isoWeek: (Int64, Int64)

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

类型：(Int64, Int64)

prop minute

public prop minute: Int64

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

类型：Int64

prop month

public prop month: Month

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

类型：Month

prop monthValue

public prop monthValue: Int64

功能：获取 DateTime 实例以数字形式表示的月份。

类型：Int64

prop nanosecond

public prop nanosecond: Int64

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

类型：Int64

prop second

public prop second: Int64

功能：获取 DateTime 实例的秒。

类型：Int64

prop year

public prop year: Int64

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

类型：Int64

prop zone

public prop zone: TimeZone

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

类型：TimeZone

prop zoneId

public prop zoneId: String

功能：获取 DateTime 实例所关联的 TimeZone 实例的时区 ID。

类型：String

prop zoneOffset

public prop zoneOffset: Duration

功能：获取 DateTime 实例所关联的 TimeZone 实例的时间偏移。

类型：Duration

static func fromUnixTimeStamp(Duration)

public static func fromUnixTimeStamp(d: Duration): DateTime

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

参数：

返回值：

异常：

static func now(TimeZone)

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

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

参数：

  • timeZone!: TimeZone - 时区，默认为本地时区。

返回值：

  • DateTime - 返回指定时区当前时间。

static func nowUTC()

public static func nowUTC(): DateTime

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

返回值：

static func of(Int64, Int64, Int64, Int64, Int64, Int64, Int64, TimeZone)

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!: Int64 - 年，范围[-999,999,999, 999,999,999]。
  • month!: Int64 - 月，范围[1, 12]。
  • dayOfMonth!: Int64 - 日，范围[1, 31]，最大取值需要跟 month 匹配，可能是 28、29、30、31。
  • hour!: Int64 - 时，范围[0, 23]。
  • minute!: Int64 - 分，范围[0, 59]。
  • second!: Int64 - 秒，范围[0, 59]。
  • nanosecond!: Int64 - 纳秒，范围[0, 999,999,999]。
  • timeZone!: TimeZone - 时区。

返回值：

异常：

static func of(Int64, Month, Int64, Int64, Int64, Int64, Int64, TimeZone)

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!: Int64 - 年，范围[-999,999,999, 999,999,999]。
  • month!: Month - 月，Month 类型。
  • dayOfMonth!: Int64 - 日，范围[1, 31]，最大取值需要跟 month 匹配，可能是 28、29、30、31。
  • hour!: Int64 - 时，范围[0, 23]。
  • minute!: Int64 - 分，范围[0, 59]。
  • second!: Int64 - 秒，范围[0, 59]。
  • nanosecond!: Int64 - 纳秒，范围[0, 999,999,999]。
  • timeZone!: TimeZone - 时区。

返回值：

异常：

static func ofEpoch(Int64, Int64)

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

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

参数：

  • second!: Int64 - unix 时间的秒部分。
  • nanosecond!: Int64 - unix 时间的纳秒部分，范围不可以超过[0, 999,999,999]。

返回值：

异常：

static func ofUTC(Int64, Int64, Int64, Int64, Int64, Int64, Int64, TimeZone)

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!: Int64 - 年，范围[-999,999,999, 999,999,999]。
  • month!: Int64 - 月，范围[1, 12]。
  • dayOfMonth!: Int64 - 日，范围[1, 31]，最大取值需要跟 month 匹配，可能是 28、29、30、31。
  • hour!: Int64 - 时，范围[0, 23]。
  • minute!: Int64 - 分，范围[0, 59]。
  • second!: Int64 - 秒，范围[0, 59]。
  • nanosecond!: Int64 - 纳秒，范围[0, 999,999,999]。

返回值：

异常：

static func ofUTC(Int64, Month, Int64, Int64, Int64, Int64, Int64, TimeZone)

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!: Int64 - 年，范围[-999,999,999, 999,999,999]。
  • month!: Month - 月，Month 类型
  • dayOfMonth!: Int64 - 日, 范围[1, 31]，最大取值需要跟 month 匹配，可能是 28、29、30、31。
  • hour!: Int64 - 时，范围[0, 23]。
  • minute!: Int64 - 分，范围[0, 59]。
  • second!: Int64 - 秒，范围[0, 59]。
  • nanosecond!: Int64 - 纳秒，范围[0, 999,999,999]。

返回值：

异常：

static func parse(String)

public static func parse(str: String): DateTime

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

参数：

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

返回值：

异常：

static func parse(String, String)

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

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

参数：

  • str: String - 时间字符串，例如："2023/04/10 08:00:00 +08:00"。
  • format: String - 时间字符串的格式，例如："yyyy/MM/dd HH:mm:ss OOOO"。格式说明详见时间字符串格式。

返回值：

  • DateTime - 根据参数 format 指定的时间格式，从参数 str 中解析出的 DateTime 实例。

异常：

static func parse(String, DateTimeFormat)

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

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

参数：

  • str: String - 时间字符串，例如："2023/04/10 08:00:00 +08:00"。
  • format: DateTimeFormat - 时间格式，例如："yyyy/MM/dd HH:mm:ss OOOO"对应的时间格式。格式说明详见时间字符串格式。

返回值：

  • DateTime - 根据参数 format 指定的时间格式，从参数 str 中解析出的 DateTime 实例。

异常：

func addDays(Int64)

public func addDays(n: Int64): DateTime

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

参数：

返回值：

异常：

func addHours(Int64)

public func addHours(n: Int64): DateTime

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

参数：

返回值：

异常：

func addMinutes(Int64)

public func addMinutes(n: Int64): DateTime

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

参数：

返回值：

异常：

func addMonths(Int64)

public func addMonths(n: Int64): DateTime

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

注意：

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

参数：

返回值：

异常：

func addNanoseconds(Int64)

public func addNanoseconds(n: Int64): DateTime

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

参数：

返回值：

异常：

func addSeconds(Int64)

public func addSeconds(n: Int64): DateTime

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

参数：

返回值：

异常：

func addWeeks(Int64)

public func addWeeks(n: Int64): DateTime

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

参数：

返回值：

异常：

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

func addYears(Int64)

public func addYears(n: Int64): DateTime

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

注意：

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

参数：

返回值：

异常：

func compare(DateTime)

public func compare(rhs: DateTime): Ordering

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

参数：

返回值：

func hashCode()

public func hashCode(): Int64

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

返回值：

func inLocal()

public func inLocal(): DateTime

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

返回值：

异常：

func inTimeZone(TimeZone)

public func inTimeZone(timeZone: TimeZone): DateTime

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

参数：

返回值：

异常：

func inUTC()

public func inUTC(): DateTime

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

返回值：

异常：

func toString()

public func toString(): String

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

返回值：

func toString(String)

public func toString(format: String): String

功能：返回一个表示 DateTime 实例的字符串，其格式由参数 format 指定。格式说明详见时间字符串格式

参数：

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

返回值：

异常：

func toString(DateTimeFormat)

public func toString(format: DateTimeFormat): String

功能：返回一个表示 DateTime 实例的字符串，其格式由参数 format 指定。格式说明详见时间字符串格式

参数：

  • format: DateTimeFormat - 时间格式，其格式可为 "yyyy/MM/dd HH:mm:ss OOOO"。

返回值：

异常：

func toUnixTimeStamp()

public func toUnixTimeStamp(): Duration

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

返回值：

operator func !=(DateTime)

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

功能：判断当前 DateTime 实例是否不等于 r。

若两个 DateTime 不相等，那么它们指向的不是同一 UTC 时间。

参数：

返回值：

  • Bool - true 或 false。当前 DateTime 实例不等于 r 时，返回 true；否则，返回 false。

operator func +(Duration)

public operator func +(r: Duration): DateTime

功能：实现 DateTime 类型和 Duration 类型加法，即 DateTime + Duration 运算。

参数：

  • r: Duration - 加法的右操作数。

返回值：

异常：

operator func -(DateTime)

public operator func -(r: DateTime): Duration

功能：实现 DateTime 类型之间的减法，即 DateTime - DateTime 运算。

参数：

  • r: DateTime - 减法的右操作数。

返回值：

operator func -(Duration)

public operator func -(r: Duration): DateTime

功能：实现 DateTime 类型和 Duration 类型减法，即 DateTime - Duration 运算。

参数：

  • r: Duration - 减法的右操作数。

返回值：

异常：

operator func <(DateTime)

public operator func <(r: DateTime): Bool

功能：判断当前 DateTime 实例是否早于 r（指向更早的 UTC 时间的 DateTime 更小）。

参数：

返回值：

  • Bool - true 或 false。当前 DateTime 实例早于 r 时，返回 true；否则，返回 false。

operator func <=(DateTime)

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

功能：判断当前 DateTime 实例是否早于或等于 r（指向更早的 UTC 时间的 DateTime 更小）。

参数：

返回值：

  • Bool - true 或 false。当前 DateTime 实例早于或等于 r 时，返回 true；否则，返回 false。

operator func ==(DateTime)

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

功能：判断当前 DateTime 实例是否等于 r。

若两个 DateTime 相等，那么它们指向同一 UTC 时间。

参数：

返回值：

  • Bool - true 或 false。当前 DateTime 实例等于 r 时，返回 true；否则，返回 false。

operator func >(DateTime)

public operator func >(r: DateTime): Bool

功能：判断当前 DateTime 实例是否晚于 r（指向更晚的 UTC 时间的 DateTime 更大）。

参数：

返回值：

  • Bool - true 或 false。当前 DateTime 实例晚于 r 时，返回 true；否则，返回 false。

operator func >=(DateTime)

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

功能：判断当前 DateTime 实例是否晚于或等于 r（指向更晚的 UTC 时间的 DateTime 更大）。

参数：

返回值：

  • Bool - true 或 false。当前 DateTime 实例晚于或等于 r 时，返回 true；否则，返回 false。

struct MonoTime

public struct MonoTime <: Hashable & Comparable<MonoTime>

功能：MonoTime 表示单调时间，是一个用来衡量经过时间的时间类型，类似于一直运行的秒表，提供了获取当前时间，计算和比较等功能。

  • MonoTime 可表示的范围为 Duration.Zero 至 Duration.Max，数值表示为 [0, 263)（单位为秒），精度为纳秒。通过 now 方法创建的 MonoTime 总是晚于先使用该方式创建的 MonoTime，常用于性能测试和时间优先的任务队列。

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

    系统系统调用函数时钟类型
    Linuxclock_gettimeCLOCK_MONOTONIC
    Windowsclock_gettimeCLOCK_MONOTONIC
    macOSclock_gettimeCLOCK_MONOTONIC

父类型：

static func now()

public static func now(): MonoTime

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

返回值：

func compare(MonoTime)

public func compare(rhs: MonoTime): Ordering

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

参数：

返回值：

func hashCode()

public func hashCode(): Int64

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

返回值：

operator func !=(MonoTime)

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

功能：判断当前 MonoTime 实例是否不等于 r。

参数：

返回值：

  • Bool - true 或 false。当前 MonoTime 实例不等于 r 时，返回 true；否则，返回 false。

operator func +(Duration)

public operator func +(r: Duration): MonoTime

功能：实现 MonoTime 类型和 Duration 类型加法，即 MonoTime + Duration 运算。

参数：

返回值：

  • MonoTime - 参数 r 表示时间间隔后的单调时间。

异常：

operator func -(Duration)

public operator func -(r: Duration): MonoTime

功能：实现 MonoTime 类型和 Duration 类型减法，即 MonoTime - Duration 运算。

参数：

返回值：

  • MonoTime - 参数 r 表示时间间隔前的单调时间。

异常：

operator func -(MonoTime)

public operator func -(r: MonoTime): Duration

功能：实现 MonoTime 类型之间的减法，即 MonoTime - MonoTime 运算。

参数：

返回值：

  • Duration - 当前实例距 r 经过的时间间隔。

operator func <(MonoTime)

public operator func <(r: MonoTime): Bool

功能：判断当前 MonoTime 实例是否早于 r。

参数：

返回值：

  • Bool - true 或 false。当前 MonoTime 实例早于 r 时，返回 true；否则，返回 false。

operator func <=(MonoTime)

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

功能：判断当前 MonoTime 实例是否早于或等于 r。

参数：

返回值：

  • Bool - true 或 false。当前 MonoTime 实例早于或等于 r 时，返回 true；否则，返回 false。

operator func ==(MonoTime)

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

功能：判断当前 MonoTime 实例是否等于 r。

参数：

返回值：

  • Bool - true 或 false。当前 MonoTime 实例等于 r 时，返回 true；否则，返回 false。

operator func >(MonoTime)

public operator func >(r: MonoTime): Bool

功能：判断当前 MonoTime 实例是否晚于 r。

参数：

返回值：

  • Bool - true 或 false。当前 MonoTime 实例晚于 r 时，返回 true；否则，返回 false。

operator func >=(MonoTime)

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

功能：判断当前 MonoTime 实例是否晚于或等于 r。

参数：

返回值：

  • Bool - true 或 false。当前 MonoTime 实例晚于或等于 r 时，返回 true；否则，返回 false。